@syfthub/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2212 @@
+/**
+ * Options for HTTP requests.
+ */
+interface RequestOptions {
+    /** Whether to include the Authorization header (default: true) */
+    includeAuth?: boolean;
+    /** Whether to send body as form-urlencoded instead of JSON */
+    isFormData?: boolean;
+    /** Request-specific timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Auth tokens returned from login/refresh.
+ */
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    tokenType: string;
+}
+/**
+ * Internal HTTP client for making API requests.
+ *
+ * Handles:
+ * - Bearer token authentication
+ * - Automatic token refresh on 401 responses
+ * - JSON serialization/deserialization
+ * - snake_case <-> camelCase conversion
+ * - Error handling and exception mapping
+ */
+declare class HTTPClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    private accessToken;
+    private refreshToken;
+    private isRefreshing;
+    private refreshPromise;
+    /**
+     * Create a new HTTP client.
+     *
+     * @param baseUrl - Base URL for all API requests (without trailing slash)
+     * @param timeout - Default timeout in milliseconds (default: 30000)
+     */
+    constructor(baseUrl: string, timeout?: number);
+    /**
+     * Set authentication tokens.
+     */
+    setTokens(access: string, refresh: string): void;
+    /**
+     * Get current authentication tokens.
+     */
+    getTokens(): AuthTokens | null;
+    /**
+     * Clear authentication tokens.
+     */
+    clearTokens(): void;
+    /**
+     * Check if the client has valid tokens.
+     */
+    hasTokens(): boolean;
+    /**
+     * Make a GET request.
+     */
+    get<T>(path: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a POST request.
+     */
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a PUT request.
+     */
+    put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a PATCH request.
+     */
+    patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a DELETE request.
+     */
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Make an HTTP request with automatic retry on 401.
+     */
+    private request;
+    /**
+     * Handle the HTTP response and convert to the expected type.
+     */
+    private handleResponse;
+    /**
+     * Handle error responses by throwing appropriate exceptions.
+     */
+    private handleErrorResponse;
+    /**
+     * Extract error code and detail from API response.
+     * Used for accounting-specific error handling.
+     */
+    private extractErrorCodeAndDetail;
+    /**
+     * Extract error message from API response.
+     */
+    private extractErrorMessage;
+    /**
+     * Extract field-level validation errors from API response.
+     */
+    private extractValidationErrors;
+    /**
+     * Attempt to refresh the access token using the refresh token.
+     */
+    private attemptTokenRefresh;
+}
+
+/**
+ * Visibility levels for endpoints.
+ */
+declare const Visibility: {
+    /** Visible to everyone, no authentication required */
+    readonly PUBLIC: "public";
+    /** Only visible to the owner and collaborators */
+    readonly PRIVATE: "private";
+    /** Visible to authenticated users within the organization */
+    readonly INTERNAL: "internal";
+};
+type Visibility = (typeof Visibility)[keyof typeof Visibility];
+/**
+ * Types of endpoints.
+ */
+declare const EndpointType: {
+    /** Machine learning model endpoint */
+    readonly MODEL: "model";
+    /** Data source endpoint */
+    readonly DATA_SOURCE: "data_source";
+};
+type EndpointType = (typeof EndpointType)[keyof typeof EndpointType];
+/**
+ * User roles in the system.
+ */
+declare const UserRole: {
+    /** Administrator with full access */
+    readonly ADMIN: "admin";
+    /** Regular user */
+    readonly USER: "user";
+    /** Guest user with limited access */
+    readonly GUEST: "guest";
+};
+type UserRole = (typeof UserRole)[keyof typeof UserRole];
+/**
+ * Organization member roles.
+ */
+declare const OrganizationRole: {
+    /** Organization owner with full control */
+    readonly OWNER: "owner";
+    /** Administrator with management privileges */
+    readonly ADMIN: "admin";
+    /** Regular member */
+    readonly MEMBER: "member";
+};
+type OrganizationRole = (typeof OrganizationRole)[keyof typeof OrganizationRole];
+
+/**
+ * User account information.
+ */
+interface User {
+    readonly id: number;
+    readonly username: string;
+    readonly email: string;
+    readonly fullName: string;
+    readonly avatarUrl: string | null;
+    readonly role: UserRole;
+    readonly isActive: boolean;
+    readonly createdAt: Date;
+    readonly updatedAt: Date | null;
+    /** Domain for endpoint URL construction (e.g., "api.example.com" or "api.example.com:8080") */
+    readonly domain: string | null;
+}
+/**
+ * Input for user registration.
+ */
+interface UserRegisterInput {
+    username: string;
+    email: string;
+    password: string;
+    fullName: string;
+    /** Optional accounting service URL (can be set up later in settings) */
+    accountingServiceUrl?: string;
+    /**
+     * Optional password for the accounting service account.
+     *
+     * The backend uses a "try-create-first" approach:
+     * - **If provided (new user)**: Creates a new accounting account with this password.
+     * - **If provided (existing user)**: Validates against the existing account and links it.
+     * - **If not provided**: Auto-generates a secure password for a new account.
+     *
+     * This means you can set your own accounting password during registration
+     * without needing an existing accounting account.
+     */
+    accountingPassword?: string;
+}
+/**
+ * Input for updating user profile.
+ */
+interface UserUpdateInput {
+    username?: string;
+    email?: string;
+    fullName?: string;
+    avatarUrl?: string;
+    /** Domain for endpoint URL construction (no protocol, e.g., "api.example.com:8080") */
+    domain?: string;
+}
+/**
+ * Input for changing password.
+ */
+interface PasswordChangeInput {
+    currentPassword: string;
+    newPassword: string;
+}
+/**
+ * Credentials for connecting to an external accounting service.
+ * These are stored in the SyftHub backend and fetched via API.
+ */
+interface AccountingCredentials {
+    /** URL of the accounting service API (null if not configured) */
+    readonly url: string | null;
+    /** Email for authenticating with the accounting service (same as SyftHub email) */
+    readonly email: string;
+    /** Password for authenticating with the accounting service (null if not configured) */
+    readonly password: string | null;
+}
+
+/**
+ * Policy configuration for an endpoint.
+ */
+interface Policy {
+    readonly type: string;
+    readonly version: string;
+    readonly enabled: boolean;
+    readonly description: string;
+    readonly config: Record<string, unknown>;
+}
+/**
+ * Connection configuration for an endpoint.
+ */
+interface Connection {
+    readonly type: string;
+    readonly enabled: boolean;
+    readonly description: string;
+    readonly config: Record<string, unknown>;
+}
+/**
+ * Full endpoint model (for authenticated users viewing their own endpoints).
+ */
+interface Endpoint {
+    readonly id: number;
+    readonly userId: number | null;
+    readonly organizationId: number | null;
+    readonly name: string;
+    readonly slug: string;
+    readonly description: string;
+    readonly type: EndpointType;
+    readonly visibility: Visibility;
+    readonly isActive: boolean;
+    readonly contributors: readonly number[];
+    readonly version: string;
+    readonly readme: string;
+    readonly tags: readonly string[];
+    readonly starsCount: number;
+    readonly policies: readonly Policy[];
+    readonly connect: readonly Connection[];
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+}
+/**
+ * Public endpoint model (for browsing the hub).
+ */
+interface EndpointPublic {
+    readonly name: string;
+    readonly slug: string;
+    readonly description: string;
+    readonly type: EndpointType;
+    readonly ownerUsername: string;
+    /** Number of contributors (user IDs not exposed for privacy) */
+    readonly contributorsCount: number;
+    readonly version: string;
+    readonly readme: string;
+    readonly tags: readonly string[];
+    readonly starsCount: number;
+    readonly policies: readonly Policy[];
+    readonly connect: readonly Connection[];
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+}
+/**
+ * Input for creating a new endpoint.
+ */
+interface EndpointCreateInput {
+    name: string;
+    type: EndpointType;
+    visibility?: Visibility;
+    description?: string;
+    slug?: string;
+    version?: string;
+    readme?: string;
+    tags?: string[];
+    policies?: Policy[];
+    connect?: Connection[];
+    contributors?: number[];
+}
+/**
+ * Input for updating an existing endpoint.
+ */
+interface EndpointUpdateInput {
+    name?: string;
+    description?: string;
+    visibility?: Visibility;
+    version?: string;
+    readme?: string;
+    tags?: string[];
+    policies?: Policy[];
+    connect?: Connection[];
+    contributors?: number[];
+}
+/**
+ * Get the owner type for an endpoint.
+ *
+ * @param endpoint - The endpoint to check
+ * @returns 'user' if user-owned, 'organization' if org-owned
+ */
+declare function getEndpointOwnerType(endpoint: Endpoint): 'user' | 'organization';
+/**
+ * Get the full path for a public endpoint (owner/slug format).
+ *
+ * @param endpoint - The public endpoint
+ * @returns The path in "owner/slug" format
+ */
+declare function getEndpointPublicPath(endpoint: EndpointPublic): string;
+
+/**
+ * Accounting Models
+ *
+ * Models for the external accounting service. The accounting service manages
+ * user balances and transactions, and uses its own authentication separate
+ * from SyftHub.
+ */
+/**
+ * Transaction status in the accounting service.
+ */
+declare const TransactionStatus: {
+    /** Transaction created, awaiting confirmation */
+    readonly PENDING: "pending";
+    /** Transaction confirmed, funds transferred */
+    readonly COMPLETED: "completed";
+    /** Transaction cancelled, no funds transferred */
+    readonly CANCELLED: "cancelled";
+};
+type TransactionStatus = (typeof TransactionStatus)[keyof typeof TransactionStatus];
+/**
+ * Who created or resolved a transaction.
+ */
+declare const CreatorType: {
+    /** System-initiated transaction */
+    readonly SYSTEM: "system";
+    /** Sender-initiated transaction */
+    readonly SENDER: "sender";
+    /** Recipient-initiated transaction (delegated) */
+    readonly RECIPIENT: "recipient";
+};
+type CreatorType = (typeof CreatorType)[keyof typeof CreatorType];
+/**
+ * User from accounting service with balance.
+ *
+ * This represents the user's account in the external accounting service,
+ * which is separate from the SyftHub user account.
+ */
+interface AccountingUser {
+    readonly id: string;
+    readonly email: string;
+    readonly balance: number;
+    readonly organization: string | null;
+}
+/**
+ * Transaction record from accounting service.
+ *
+ * Transactions go through a lifecycle:
+ * 1. Created (status=PENDING)
+ * 2. Confirmed or Cancelled (status=COMPLETED or CANCELLED)
+ *
+ * The createdBy field indicates who initiated the transaction:
+ * - SENDER: Direct transaction by the payer
+ * - RECIPIENT: Delegated transaction using a token
+ * - SYSTEM: System-initiated transaction
+ *
+ * The resolvedBy field indicates who confirmed/cancelled.
+ */
+interface Transaction {
+    readonly id: string;
+    readonly senderEmail: string;
+    readonly recipientEmail: string;
+    readonly amount: number;
+    readonly status: TransactionStatus;
+    readonly createdBy: CreatorType;
+    readonly resolvedBy: CreatorType | null;
+    readonly createdAt: Date;
+    readonly resolvedAt: Date | null;
+    readonly appName: string | null;
+    readonly appEpPath: string | null;
+}
+/**
+ * Input for creating a direct transaction.
+ */
+interface CreateTransactionInput {
+    /** Email of the recipient */
+    recipientEmail: string;
+    /** Amount to transfer (must be > 0) */
+    amount: number;
+    /** Optional app name for context (e.g., "syftai-space") */
+    appName?: string;
+    /** Optional endpoint path for context (e.g., "alice/model") */
+    appEpPath?: string;
+}
+/**
+ * Input for creating a delegated transaction.
+ */
+interface CreateDelegatedTransactionInput {
+    /** Email of the sender who created the token */
+    senderEmail: string;
+    /** Amount to transfer (must be > 0) */
+    amount: number;
+    /** JWT token from sender's createTransactionToken() */
+    token: string;
+}
+/**
+ * Input for updating password.
+ */
+interface UpdatePasswordInput {
+    /** Current password for verification */
+    currentPassword: string;
+    /** New password to set */
+    newPassword: string;
+}
+/**
+ * Raw transaction response from API (before date parsing).
+ */
+interface TransactionResponse {
+    id: string;
+    senderEmail: string;
+    recipientEmail: string;
+    amount: number;
+    status: TransactionStatus;
+    createdBy: CreatorType;
+    resolvedBy: CreatorType | null;
+    createdAt: string;
+    resolvedAt: string | null;
+    appName: string | null;
+    appEpPath: string | null;
+}
+/**
+ * Token response from createTransactionToken.
+ */
+interface TransactionTokenResponse {
+    token: string;
+}
+/**
+ * Parse a transaction response into a Transaction object.
+ */
+declare function parseTransaction(response: TransactionResponse): Transaction;
+/**
+ * Check if a transaction is pending.
+ */
+declare function isTransactionPending(tx: Transaction): boolean;
+/**
+ * Check if a transaction is completed.
+ */
+declare function isTransactionCompleted(tx: Transaction): boolean;
+/**
+ * Check if a transaction is cancelled.
+ */
+declare function isTransactionCancelled(tx: Transaction): boolean;
+
+/**
+ * Chat-related types for the SyftHub SDK.
+ *
+ * These types are used for interacting with the Aggregator service
+ * for RAG (Retrieval-Augmented Generation) workflows.
+ */
+/**
+ * Reference to a SyftAI-Space endpoint with connection details.
+ *
+ * Can be constructed directly or resolved from an EndpointPublic object.
+ *
+ * @example
+ * const ref: EndpointRef = {
+ *   url: 'http://syftai-space:8080',
+ *   slug: 'my-model',
+ *   name: 'My Model',
+ *   ownerUsername: 'alice',
+ * };
+ */
+interface EndpointRef {
+    /** Base URL of the SyftAI-Space instance */
+    url: string;
+    /** Endpoint slug for the API path */
+    slug: string;
+    /** Display name of the endpoint */
+    name?: string;
+    /** Tenant name for X-Tenant-Name header */
+    tenantName?: string;
+    /** Owner's username - used as the audience for satellite token authentication */
+    ownerUsername?: string;
+}
+/**
+ * A document retrieved from a data source.
+ */
+interface Document {
+    /** The document content */
+    content: string;
+    /** Relevance score (0-1) */
+    score: number;
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Status of a data source query.
+ */
+type SourceStatus = 'success' | 'error' | 'timeout';
+/**
+ * Information about a data source retrieval (metadata).
+ */
+interface SourceInfo {
+    /** Endpoint path (owner/slug) */
+    path: string;
+    /** Number of documents retrieved from this source */
+    documentsRetrieved: number;
+    /** Query status */
+    status: SourceStatus;
+    /** Error message if status is error/timeout */
+    errorMessage?: string;
+}
+/**
+ * A document source entry with endpoint path and content.
+ * Used in the sources dict of ChatResponse, keyed by document title.
+ */
+interface DocumentSource {
+    /** Endpoint path (owner/slug) where document was retrieved */
+    slug: string;
+    /** The actual document content */
+    content: string;
+}
+/**
+ * Timing metadata for chat response.
+ */
+interface ChatMetadata {
+    /** Time spent retrieving documents (ms) */
+    retrievalTimeMs: number;
+    /** Time spent generating response (ms) */
+    generationTimeMs: number;
+    /** Total request time (ms) */
+    totalTimeMs: number;
+}
+/**
+ * Token usage information from model generation.
+ */
+interface TokenUsage {
+    /** Number of tokens in the prompt */
+    promptTokens: number;
+    /** Number of tokens in the completion */
+    completionTokens: number;
+    /** Total tokens used */
+    totalTokens: number;
+}
+/**
+ * Response from a chat completion request.
+ */
+interface ChatResponse {
+    /** The generated response text */
+    response: string;
+    /** Retrieved documents keyed by title, with endpoint slug and content */
+    sources: Record<string, DocumentSource>;
+    /** Metadata about each data source retrieval (status, count, errors) */
+    retrievalInfo: SourceInfo[];
+    /** Timing metadata */
+    metadata: ChatMetadata;
+    /** Token usage if available */
+    usage?: TokenUsage;
+}
+/**
+ * A chat message for model queries.
+ */
+interface Message {
+    /** Message role (system, user, assistant) */
+    role: 'system' | 'user' | 'assistant';
+    /** Message content */
+    content: string;
+}
+/**
+ * Options for chat completion.
+ */
+interface ChatOptions {
+    /** The user's question or prompt */
+    prompt: string;
+    /** Model endpoint (path string, EndpointRef, or EndpointPublic) */
+    model: string | EndpointRef;
+    /** Optional list of data source endpoints for context */
+    dataSources?: (string | EndpointRef)[];
+    /** Number of documents to retrieve per source (default: 5) */
+    topK?: number;
+    /** Maximum tokens to generate (default: 1024) */
+    maxTokens?: number;
+    /** Generation temperature (default: 0.7) */
+    temperature?: number;
+    /** Minimum similarity for retrieved docs (default: 0.5) */
+    similarityThreshold?: number;
+    /** AbortSignal for request cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Options for querying a data source directly.
+ */
+interface QueryDataSourceOptions {
+    /** EndpointRef with URL and slug */
+    endpoint: EndpointRef;
+    /** The search query */
+    query: string;
+    /** User email for visibility/policy checks */
+    userEmail: string;
+    /** Number of documents to retrieve (default: 5) */
+    topK?: number;
+    /** Minimum similarity score (default: 0.5) */
+    similarityThreshold?: number;
+}
+/**
+ * Options for querying a model directly.
+ */
+interface QueryModelOptions {
+    /** EndpointRef with URL and slug */
+    endpoint: EndpointRef;
+    /** List of chat messages */
+    messages: Message[];
+    /** User email for visibility/policy checks */
+    userEmail: string;
+    /** Maximum tokens to generate (default: 1024) */
+    maxTokens?: number;
+    /** Generation temperature (default: 0.7) */
+    temperature?: number;
+}
+/**
+ * Fired when retrieval begins.
+ */
+interface RetrievalStartEvent {
+    type: 'retrieval_start';
+    sourceCount: number;
+}
+/**
+ * Fired when a single source finishes querying.
+ */
+interface SourceCompleteEvent {
+    type: 'source_complete';
+    path: string;
+    status: string;
+    documentsRetrieved: number;
+}
+/**
+ * Fired when all retrieval is done.
+ */
+interface RetrievalCompleteEvent {
+    type: 'retrieval_complete';
+    totalDocuments: number;
+    timeMs: number;
+}
+/**
+ * Fired when model generation begins.
+ */
+interface GenerationStartEvent {
+    type: 'generation_start';
+}
+/**
+ * Fired for each token from the model.
+ */
+interface TokenEvent {
+    type: 'token';
+    content: string;
+}
+/**
+ * Fired when generation completes successfully.
+ */
+interface DoneEvent {
+    type: 'done';
+    /** Retrieved documents keyed by title, with endpoint slug and content */
+    sources: Record<string, DocumentSource>;
+    /** Metadata about each data source retrieval (status, count, errors) */
+    retrievalInfo: SourceInfo[];
+    metadata: ChatMetadata;
+    /** Token usage if available (only from non-streaming mode) */
+    usage?: TokenUsage;
+}
+/**
+ * Fired on error.
+ */
+interface ErrorEvent {
+    type: 'error';
+    message: string;
+}
+/**
+ * Discriminated union of all streaming event types.
+ *
+ * Use type narrowing to handle each event type:
+ *
+ * @example
+ * for await (const event of client.chat.stream(options)) {
+ *   switch (event.type) {
+ *     case 'token':
+ *       process.stdout.write(event.content);
+ *       break;
+ *     case 'done':
+ *       console.log(`\nCompleted in ${event.metadata.totalTimeMs}ms`);
+ *       break;
+ *     case 'error':
+ *       console.error(`Error: ${event.message}`);
+ *       break;
+ *   }
+ * }
+ */
+type ChatStreamEvent = RetrievalStartEvent | SourceCompleteEvent | RetrievalCompleteEvent | GenerationStartEvent | TokenEvent | DoneEvent | ErrorEvent;
+
+/**
+ * Authentication resource for login, register, and session management.
+ *
+ * @example
+ * // Register a new user
+ * const user = await client.auth.register({
+ *   username: 'alice',
+ *   email: 'alice@example.com',
+ *   password: 'SecurePass123!',
+ *   fullName: 'Alice'
+ * });
+ *
+ * @example
+ * // Login
+ * const user = await client.auth.login('alice', 'SecurePass123!');
+ *
+ * @example
+ * // Get current user
+ * const me = await client.auth.me();
+ *
+ * @example
+ * // Logout
+ * await client.auth.logout();
+ */
+declare class AuthResource {
+    private readonly http;
+    constructor(http: HTTPClient);
+    /**
+     * Register a new user account.
+     *
+     * If an accounting service URL is configured (via `accountingServiceUrl` or server default),
+     * the backend will handle accounting integration using a "try-create-first" approach:
+     *
+     * **Accounting Password Behavior:**
+     * - **Not provided**: A secure password is auto-generated and a new accounting account is created.
+     * - **Provided (new user)**: The account is created with your chosen password.
+     * - **Provided (existing user)**: Your password is validated and accounts are linked.
+     *
+     * This means you can set your own accounting password during registration even if you're
+     * a new user - you don't need an existing accounting account first.
+     *
+     * @param input - Registration details (username, email, password, fullName)
+     * @returns The created User
+     * @throws {ValidationError} If input validation fails
+     * @throws {UserAlreadyExistsError} If username or email already exists in SyftHub
+     * @throws {AccountingAccountExistsError} If email already exists in accounting service
+     *         and no `accountingPassword` was provided. Retry with the password.
+     * @throws {InvalidAccountingPasswordError} If the provided accounting password doesn't
+     *         match an existing accounting account
+     * @throws {AccountingServiceUnavailableError} If the accounting service is unreachable
+     *
+     * @example
+     * // Basic registration (auto-generated accounting password)
+     * const user = await client.auth.register({
+     *   username: 'alice',
+     *   email: 'alice@example.com',
+     *   password: 'SecurePass123!',
+     *   fullName: 'Alice'
+     * });
+     *
+     * @example
+     * // Registration with custom accounting password (NEW user)
+     * const user = await client.auth.register({
+     *   username: 'bob',
+     *   email: 'bob@example.com',
+     *   password: 'SecurePass123!',
+     *   fullName: 'Bob',
+     *   accountingPassword: 'MyChosenAccountingPass!'  // Creates account with this password
+     * });
+     *
+     * @example
+     * // Handle existing accounting account
+     * try {
+     *   await client.auth.register({ username, email, password, fullName });
+     * } catch (error) {
+     *   if (error instanceof AccountingAccountExistsError) {
+     *     // Prompt user for their existing accounting password
+     *     const accountingPassword = await promptUser('Enter your existing accounting password:');
+     *     await client.auth.register({ username, email, password, fullName, accountingPassword });
+     *   } else {
+     *     throw error;
+     *   }
+     * }
+     */
+    register(input: UserRegisterInput): Promise<User>;
+    /**
+     * Login with username/email and password.
+     *
+     * Uses OAuth2 password flow (form-urlencoded body).
+     *
+     * @param username - Username or email
+     * @param password - Password
+     * @returns The authenticated User
+     * @throws {AuthenticationError} If credentials are invalid
+     */
+    login(username: string, password: string): Promise<User>;
+    /**
+     * Logout the current user.
+     *
+     * Invalidates tokens on the server and clears local token storage.
+     */
+    logout(): Promise<void>;
+    /**
+     * Get the current authenticated user.
+     *
+     * @returns The current User
+     * @throws {AuthenticationError} If not authenticated
+     */
+    me(): Promise<User>;
+    /**
+     * Manually refresh the access token.
+     *
+     * This is normally handled automatically when a request returns 401.
+     *
+     * @throws {AuthenticationError} If refresh token is invalid or expired
+     */
+    refresh(): Promise<void>;
+    /**
+     * Change the current user's password.
+     *
+     * @param currentPassword - Current password for verification
+     * @param newPassword - New password to set
+     * @throws {AuthenticationError} If current password is incorrect
+     * @throws {ValidationError} If new password doesn't meet requirements
+     */
+    changePassword(currentPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Get a satellite token for a specific audience (target service).
+     *
+     * Satellite tokens are short-lived, RS256-signed JWTs that allow satellite
+     * services (like SyftAI-Space) to verify user identity without calling
+     * SyftHub for every request.
+     *
+     * @param audience - Target service identifier (username of the service owner)
+     * @returns Satellite token response with token and expiry
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {ValidationError} If audience is invalid or inactive
+     *
+     * @example
+     * // Get a token for querying alice's SyftAI-Space endpoints
+     * const tokenResponse = await client.auth.getSatelliteToken('alice');
+     * console.log(`Token expires in ${tokenResponse.expiresIn} seconds`);
+     */
+    getSatelliteToken(audience: string): Promise<SatelliteTokenResponse>;
+    /**
+     * Get satellite tokens for multiple audiences in parallel.
+     *
+     * This is useful when making requests to endpoints owned by different users.
+     * Tokens are cached and reused where possible.
+     *
+     * @param audiences - Array of unique audience identifiers (usernames)
+     * @returns Map of audience to satellite token
+     * @throws {AuthenticationError} If not authenticated
+     *
+     * @example
+     * // Get tokens for multiple endpoint owners
+     * const tokens = await client.auth.getSatelliteTokens(['alice', 'bob']);
+     * console.log(`Got ${tokens.size} tokens`);
+     */
+    getSatelliteTokens(audiences: string[]): Promise<Map<string, string>>;
+    /**
+     * Get transaction tokens for multiple endpoint owners.
+     *
+     * Transaction tokens are short-lived JWTs that pre-authorize the endpoint owner
+     * (recipient) to charge the current user (sender) for usage. These tokens are
+     * created via the accounting service and passed to the aggregator.
+     *
+     * This is used by the chat flow to enable billing for endpoint usage.
+     *
+     * @param ownerUsernames - Array of endpoint owner usernames
+     * @returns TransactionTokensResponse with tokens map and any errors
+     * @throws {AuthenticationError} If not authenticated
+     *
+     * @example
+     * // Get transaction tokens for endpoint owners
+     * const response = await client.auth.getTransactionTokens(['alice', 'bob']);
+     * console.log(`Got ${Object.keys(response.tokens).length} tokens`);
+     * if (Object.keys(response.errors).length > 0) {
+     *   console.log('Some tokens failed:', response.errors);
+     * }
+     */
+    getTransactionTokens(ownerUsernames: string[]): Promise<TransactionTokensResponse>;
+}
+/**
+ * Response from satellite token endpoint.
+ */
+interface SatelliteTokenResponse {
+    /** RS256-signed JWT for the target service */
+    targetToken: string;
+    /** Seconds until the token expires */
+    expiresIn: number;
+}
+/**
+ * Response from transaction tokens endpoint.
+ */
+interface TransactionTokensResponse {
+    /** Mapping of owner_username to transaction token */
+    tokens: Record<string, string>;
+    /** Mapping of owner_username to error message (for failed tokens) */
+    errors: Record<string, string>;
+}
+
+/**
+ * Users resource for profile management and availability checks.
+ *
+ * @example
+ * // Update your profile
+ * const user = await client.users.update({
+ *   fullName: 'Alice Smith',
+ *   avatarUrl: 'https://example.com/avatar.jpg'
+ * });
+ *
+ * @example
+ * // Check if username is available
+ * const available = await client.users.checkUsername('newusername');
+ *
+ * @example
+ * // Check if email is available
+ * const available = await client.users.checkEmail('new@example.com');
+ */
+declare class UsersResource {
+    private readonly http;
+    constructor(http: HTTPClient);
+    /**
+     * Update the current user's profile.
+     *
+     * Only provided fields will be updated.
+     *
+     * @param input - Fields to update
+     * @returns The updated User
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {ValidationError} If input validation fails
+     */
+    update(input: UserUpdateInput): Promise<User>;
+    /**
+     * Check if a username is available.
+     *
+     * @param username - Username to check
+     * @returns True if the username is available
+     */
+    checkUsername(username: string): Promise<boolean>;
+    /**
+     * Check if an email is available.
+     *
+     * @param email - Email to check
+     * @returns True if the email is available
+     */
+    checkEmail(email: string): Promise<boolean>;
+    /**
+     * Get the current user's accounting service credentials.
+     *
+     * Returns credentials stored in SyftHub for connecting to an external
+     * accounting service. The email is always the same as the user's SyftHub email.
+     *
+     * @returns Accounting credentials (url and password may be null if not configured)
+     * @throws {AuthenticationError} If not authenticated
+     *
+     * @example
+     * const credentials = await client.users.getAccountingCredentials();
+     * if (credentials.url && credentials.password) {
+     *   // Use credentials to connect to accounting service
+     * }
+     */
+    getAccountingCredentials(): Promise<AccountingCredentials>;
+}
+
+/**
+ * Function type for fetching a page of items.
+ */
+type PageFetcher<T> = (skip: number, limit: number) => Promise<T[]>;
+/**
+ * Lazy async iterator for paginated API responses.
+ *
+ * Fetches pages on demand as you iterate, minimizing API calls
+ * and memory usage for large datasets.
+ *
+ * @example
+ * // Iterate through all items
+ * for await (const endpoint of client.hub.browse()) {
+ *   console.log(endpoint.name);
+ * }
+ *
+ * @example
+ * // Get just the first page
+ * const firstPage = await client.hub.browse().firstPage();
+ *
+ * @example
+ * // Get first 10 items
+ * const top10 = await client.hub.browse().take(10);
+ */
+declare class PageIterator<T> implements AsyncIterable<T> {
+    private readonly fetcher;
+    private readonly pageSize;
+    private items;
+    private index;
+    private skip;
+    private exhausted;
+    private initialized;
+    /**
+     * Create a new PageIterator.
+     *
+     * @param fetcher - Function that fetches a page of items given skip and limit
+     * @param pageSize - Number of items to fetch per page (default: 20)
+     */
+    constructor(fetcher: PageFetcher<T>, pageSize?: number);
+    /**
+     * Async iterator implementation for `for await...of` loops.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /**
+     * Get just the first page of results.
+     *
+     * @returns Promise resolving to the first page of items
+     */
+    firstPage(): Promise<T[]>;
+    /**
+     * Get all items across all pages.
+     *
+     * Warning: This loads all items into memory. For large datasets,
+     * consider iterating with `for await...of` instead.
+     *
+     * @returns Promise resolving to all items
+     */
+    all(): Promise<T[]>;
+    /**
+     * Get the first N items.
+     *
+     * @param n - Maximum number of items to return
+     * @returns Promise resolving to up to N items
+     */
+    take(n: number): Promise<T[]>;
+    /**
+     * Fetch the next page of items from the API.
+     */
+    private fetchNextPage;
+}
+
+/**
+ * Options for listing endpoints.
+ */
+interface ListEndpointsOptions {
+    /** Filter by visibility level */
+    visibility?: Visibility;
+    /** Number of items per page (default: 20) */
+    pageSize?: number;
+}
+/**
+ * My Endpoints resource for CRUD operations on user's own endpoints.
+ *
+ * For browsing public endpoints from other users, see the Hub resource.
+ *
+ * @example
+ * // List your endpoints
+ * for await (const endpoint of client.myEndpoints.list()) {
+ *   console.log(endpoint.name);
+ * }
+ *
+ * @example
+ * // Create a new endpoint
+ * const endpoint = await client.myEndpoints.create({
+ *   name: 'My API',
+ *   type: 'model',
+ *   visibility: 'public',
+ *   description: 'A cool API'
+ * });
+ *
+ * @example
+ * // Get a specific endpoint
+ * const endpoint = await client.myEndpoints.get('alice/my-api');
+ *
+ * @example
+ * // Update an endpoint
+ * const updated = await client.myEndpoints.update('alice/my-api', {
+ *   description: 'Updated description'
+ * });
+ *
+ * @example
+ * // Delete an endpoint
+ * await client.myEndpoints.delete('alice/my-api');
+ */
+declare class MyEndpointsResource {
+    private readonly http;
+    constructor(http: HTTPClient);
+    /**
+     * Parse an endpoint path into owner and slug.
+     *
+     * @param path - Path in "owner/slug" format
+     * @returns Tuple of [owner, slug]
+     * @throws {Error} If path format is invalid
+     */
+    private parsePath;
+    /**
+     * Resolve an endpoint path to its ID.
+     *
+     * @param path - Endpoint path in "owner/slug" format
+     * @returns The endpoint ID
+     */
+    private resolveEndpointId;
+    /**
+     * List the current user's endpoints.
+     *
+     * @param options - Filtering and pagination options
+     * @returns PageIterator that lazily fetches endpoints
+     * @throws {AuthenticationError} If not authenticated
+     */
+    list(options?: ListEndpointsOptions): PageIterator<Endpoint>;
+    /**
+     * Create a new endpoint.
+     *
+     * @param input - Endpoint creation details
+     * @param organizationId - Optional organization ID (for org-owned endpoints)
+     * @returns The created Endpoint
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {ValidationError} If input validation fails
+     */
+    create(input: EndpointCreateInput, organizationId?: number): Promise<Endpoint>;
+    /**
+     * Get a specific endpoint by path.
+     *
+     * @param path - Endpoint path in "owner/slug" format (e.g., "alice/my-api")
+     * @returns The Endpoint
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NotFoundError} If endpoint not found
+     * @throws {AuthorizationError} If not authorized to view
+     */
+    get(path: string): Promise<Endpoint>;
+    /**
+     * Update an endpoint.
+     *
+     * Only provided fields will be updated.
+     *
+     * @param path - Endpoint path in "owner/slug" format
+     * @param input - Fields to update
+     * @returns The updated Endpoint
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NotFoundError} If endpoint not found
+     * @throws {AuthorizationError} If not owner/admin
+     */
+    update(path: string, input: EndpointUpdateInput): Promise<Endpoint>;
+    /**
+     * Delete an endpoint.
+     *
+     * @param path - Endpoint path in "owner/slug" format
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NotFoundError} If endpoint not found
+     * @throws {AuthorizationError} If not owner/admin
+     */
+    delete(path: string): Promise<void>;
+}
+
+/**
+ * Options for browsing endpoints.
+ */
+interface BrowseOptions {
+    /** Number of items per page (default: 20) */
+    pageSize?: number;
+}
+/**
+ * Options for trending endpoints.
+ */
+interface TrendingOptions {
+    /** Minimum number of stars */
+    minStars?: number;
+    /** Number of items per page (default: 20) */
+    pageSize?: number;
+}
+/**
+ * Hub resource for browsing and discovering public endpoints.
+ *
+ * For managing your own endpoints, see the MyEndpoints resource.
+ *
+ * @example
+ * // Browse all public endpoints
+ * for await (const endpoint of client.hub.browse()) {
+ *   console.log(`${endpoint.ownerUsername}/${endpoint.slug}: ${endpoint.name}`);
+ * }
+ *
+ * @example
+ * // Get trending endpoints
+ * for await (const endpoint of client.hub.trending({ minStars: 10 })) {
+ *   console.log(`${endpoint.name} - ${endpoint.starsCount} stars`);
+ * }
+ *
+ * @example
+ * // Get a specific endpoint
+ * const endpoint = await client.hub.get('alice/cool-api');
+ * console.log(endpoint.readme);
+ *
+ * @example
+ * // Star an endpoint (requires auth)
+ * await client.hub.star('alice/cool-api');
+ *
+ * @example
+ * // Check if you've starred an endpoint
+ * const starred = await client.hub.isStarred('alice/cool-api');
+ */
+declare class HubResource {
+    private readonly http;
+    constructor(http: HTTPClient);
+    /**
+     * Parse an endpoint path into owner and slug.
+     *
+     * @param path - Path in "owner/slug" format
+     * @returns Tuple of [owner, slug]
+     */
+    private parsePath;
+    /**
+     * Resolve an endpoint path to its ID.
+     *
+     * This searches the user's own endpoints to find the ID.
+     *
+     * @param path - Endpoint path in "owner/slug" format
+     * @returns The endpoint ID
+     */
+    private resolveEndpointId;
+    /**
+     * Browse all public endpoints.
+     *
+     * @param options - Pagination options
+     * @returns PageIterator that lazily fetches endpoints
+     */
+    browse(options?: BrowseOptions): PageIterator<EndpointPublic>;
+    /**
+     * Get trending endpoints sorted by stars.
+     *
+     * @param options - Filter and pagination options
+     * @returns PageIterator that lazily fetches endpoints
+     */
+    trending(options?: TrendingOptions): PageIterator<EndpointPublic>;
+    /**
+     * Get an endpoint by its path.
+     *
+     * This method searches the public endpoints API to find the endpoint,
+     * which works reliably across all deployment configurations.
+     *
+     * @param path - Endpoint path in "owner/slug" format (e.g., "alice/cool-api")
+     * @returns The EndpointPublic
+     * @throws {NotFoundError} If endpoint not found
+     */
+    get(path: string): Promise<EndpointPublic>;
+    /**
+     * Star an endpoint.
+     *
+     * @param path - Endpoint path in "owner/slug" format
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NotFoundError} If endpoint not found
+     */
+    star(path: string): Promise<void>;
+    /**
+     * Unstar an endpoint.
+     *
+     * @param path - Endpoint path in "owner/slug" format
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NotFoundError} If endpoint not found
+     */
+    unstar(path: string): Promise<void>;
+    /**
+     * Check if you have starred an endpoint.
+     *
+     * @param path - Endpoint path in "owner/slug" format
+     * @returns True if starred, False otherwise
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NotFoundError} If endpoint not found
+     */
+    isStarred(path: string): Promise<boolean>;
+}
+
+/**
+ * Accounting Resource for SyftHub SDK
+ *
+ * This module connects to an external accounting/billing service for managing
+ * user balances and transactions. The accounting service is separate from SyftHub
+ * and uses its own authentication (Basic auth with email/password).
+ *
+ * @example
+ * ```typescript
+ * // Create accounting client
+ * const accounting = new AccountingResource({
+ *   url: 'https://accounting.example.com',
+ *   email: 'user@example.com',
+ *   password: 'secret'
+ * });
+ *
+ * // Get user balance
+ * const user = await accounting.getUser();
+ * console.log(`Balance: ${user.balance}`);
+ *
+ * // Create a transaction
+ * const tx = await accounting.createTransaction({
+ *   recipientEmail: 'recipient@example.com',
+ *   amount: 10.0,
+ *   appName: 'syftai-space',
+ *   appEpPath: 'alice/my-model'
+ * });
+ *
+ * // Confirm the transaction
+ * await accounting.confirmTransaction(tx.id);
+ * ```
+ */
+
+/**
+ * Options for creating an AccountingResource.
+ */
+interface AccountingResourceOptions {
+    /** Accounting service URL */
+    url: string;
+    /** Email for Basic auth */
+    email: string;
+    /** Password for Basic auth */
+    password: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Options for listing transactions.
+ */
+interface TransactionsOptions {
+    /** Number of items per page (default: 20) */
+    pageSize?: number;
+}
+/**
+ * Handle accounting/billing operations with external service.
+ *
+ * The accounting service manages user balances and transactions. It uses
+ * Basic auth (email/password) for authentication, which is separate from
+ * SyftHub's JWT-based authentication.
+ *
+ * Transaction Workflow:
+ * 1. Sender creates transaction (status=PENDING)
+ * 2. Either party confirms (status=COMPLETED) or cancels (status=CANCELLED)
+ *
+ * Delegated Transaction Workflow:
+ * 1. Sender creates a transaction token for recipient
+ * 2. Recipient uses token to create delegated transaction
+ * 3. Recipient confirms the transaction
+ */
+declare class AccountingResource {
+    private readonly baseUrl;
+    private readonly email;
+    private readonly password;
+    private readonly timeout;
+    private readonly authHeader;
+    constructor(options: AccountingResourceOptions);
+    /**
+     * Make an authenticated request to the accounting service.
+     */
+    private request;
+    /**
+     * Make a request using Bearer token auth (for delegated transactions).
+     */
+    private requestWithToken;
+    /**
+     * Get the current user's account information including balance.
+     *
+     * @returns AccountingUser with id, email, balance, and organization
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {APIError} On other errors
+     *
+     * @example
+     * ```typescript
+     * const user = await accounting.getUser();
+     * console.log(`Balance: ${user.balance}`);
+     * console.log(`Organization: ${user.organization}`);
+     * ```
+     */
+    getUser(): Promise<AccountingUser>;
+    /**
+     * Update the user's password.
+     *
+     * @param currentPassword - Current password for verification
+     * @param newPassword - New password to set
+     * @throws {AuthenticationError} If current password is wrong
+     * @throws {ValidationError} If new password doesn't meet requirements
+     *
+     * @example
+     * ```typescript
+     * await accounting.updatePassword('old_secret', 'new_secret');
+     * ```
+     */
+    updatePassword(currentPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Update the user's organization.
+     *
+     * @param organization - New organization name
+     * @throws {AuthenticationError} If authentication fails
+     *
+     * @example
+     * ```typescript
+     * await accounting.updateOrganization('OpenMined');
+     * ```
+     */
+    updateOrganization(organization: string): Promise<void>;
+    /**
+     * List account transactions with pagination.
+     *
+     * Returns a lazy iterator that fetches pages on demand.
+     *
+     * @param options - Pagination options
+     * @returns PageIterator that yields Transaction objects
+     *
+     * @example
+     * ```typescript
+     * // Iterate through all transactions
+     * for await (const tx of accounting.getTransactions()) {
+     *   console.log(`${tx.createdAt}: ${tx.amount} from ${tx.senderEmail}`);
+     * }
+     *
+     * // Get first page only
+     * const firstPage = await accounting.getTransactions().firstPage();
+     *
+     * // Get all transactions
+     * const allTxs = await accounting.getTransactions().all();
+     * ```
+     */
+    getTransactions(options?: TransactionsOptions): PageIterator<Transaction>;
+    /**
+     * Get a specific transaction by ID.
+     *
+     * @param transactionId - The transaction ID
+     * @returns Transaction object
+     * @throws {NotFoundError} If transaction not found
+     *
+     * @example
+     * ```typescript
+     * const tx = await accounting.getTransaction('tx_123');
+     * console.log(`Status: ${tx.status}`);
+     * ```
+     */
+    getTransaction(transactionId: string): Promise<Transaction>;
+    /**
+     * Create a new transaction (direct transfer).
+     *
+     * Creates a PENDING transaction that must be confirmed or cancelled.
+     * The transaction is created by the sender (current user).
+     *
+     * @param input - Transaction details
+     * @returns Transaction in PENDING status
+     * @throws {ValidationError} If amount <= 0 or insufficient balance
+     *
+     * @example
+     * ```typescript
+     * const tx = await accounting.createTransaction({
+     *   recipientEmail: 'bob@example.com',
+     *   amount: 10.0,
+     *   appName: 'syftai-space',
+     *   appEpPath: 'alice/my-model'
+     * });
+     * console.log(`Created transaction ${tx.id}: ${tx.status}`);
+     *
+     * // Later, confirm or cancel
+     * await accounting.confirmTransaction(tx.id);
+     * ```
+     */
+    createTransaction(input: CreateTransactionInput): Promise<Transaction>;
+    /**
+     * Confirm a pending transaction.
+     *
+     * Confirms the transaction, transferring funds from sender to recipient.
+     * Can be called by either the sender or recipient.
+     *
+     * @param transactionId - The transaction ID to confirm
+     * @returns Transaction in COMPLETED status
+     * @throws {NotFoundError} If transaction not found
+     * @throws {ValidationError} If transaction is not in PENDING status
+     *
+     * @example
+     * ```typescript
+     * const tx = await accounting.confirmTransaction('tx_123');
+     * console.log(`Confirmed: ${tx.status}`); // "completed"
+     * ```
+     */
+    confirmTransaction(transactionId: string): Promise<Transaction>;
+    /**
+     * Cancel a pending transaction.
+     *
+     * Cancels the transaction without transferring funds.
+     * Can be called by either the sender or recipient.
+     *
+     * @param transactionId - The transaction ID to cancel
+     * @returns Transaction in CANCELLED status
+     * @throws {NotFoundError} If transaction not found
+     * @throws {ValidationError} If transaction is not in PENDING status
+     *
+     * @example
+     * ```typescript
+     * const tx = await accounting.cancelTransaction('tx_123');
+     * console.log(`Cancelled: ${tx.status}`); // "cancelled"
+     * ```
+     */
+    cancelTransaction(transactionId: string): Promise<Transaction>;
+    /**
+     * Create a transaction token for delegated transfers.
+     *
+     * Creates a JWT token that authorizes the recipient to create a
+     * transaction on behalf of the sender (current user). The token
+     * is short-lived (typically ~5 minutes).
+     *
+     * Use this when you want to pre-authorize a payment that will be
+     * initiated by the recipient (e.g., a service charging for usage).
+     *
+     * @param recipientEmail - Email of the authorized recipient
+     * @returns JWT token string to share with recipient
+     *
+     * @example
+     * ```typescript
+     * // Sender creates token
+     * const token = await accounting.createTransactionToken('service@example.com');
+     *
+     * // Share token with recipient out-of-band
+     * // Recipient uses token to create delegated transaction
+     * ```
+     */
+    createTransactionToken(recipientEmail: string): Promise<string>;
+    /**
+     * Create a delegated transaction using a pre-authorized token.
+     *
+     * Creates a transaction on behalf of the sender using their token.
+     * This is typically used by services to charge users for usage.
+     *
+     * The token authenticates the request instead of Basic auth.
+     *
+     * @param senderEmail - Email of the sender who created the token
+     * @param amount - Amount to transfer (must be > 0)
+     * @param token - JWT token from sender's createTransactionToken()
+     * @returns Transaction in PENDING status (createdBy=RECIPIENT)
+     * @throws {AuthenticationError} If token is invalid or expired
+     * @throws {ValidationError} If amount <= 0
+     *
+     * @example
+     * ```typescript
+     * // Recipient creates transaction using sender's token
+     * const tx = await accounting.createDelegatedTransaction(
+     *   'alice@example.com',
+     *   5.0,
+     *   aliceToken
+     * );
+     *
+     * // Recipient confirms the transaction
+     * await accounting.confirmTransaction(tx.id);
+     * ```
+     */
+    createDelegatedTransaction(senderEmail: string, amount: number, token: string): Promise<Transaction>;
+}
+/**
+ * Create a new AccountingResource instance.
+ *
+ * @param options - Configuration options
+ * @returns AccountingResource instance
+ *
+ * @example
+ * ```typescript
+ * const accounting = createAccountingResource({
+ *   url: process.env.ACCOUNTING_URL!,
+ *   email: process.env.ACCOUNTING_EMAIL!,
+ *   password: process.env.ACCOUNTING_PASSWORD!
+ * });
+ * ```
+ */
+declare function createAccountingResource(options: AccountingResourceOptions): AccountingResource;
+
+/**
+ * Base error class for all SyftHub SDK errors.
+ */
+declare class SyftHubError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when an API request fails with an error status code.
+ */
+declare class APIError extends SyftHubError {
+    readonly status: number;
+    readonly data?: unknown | undefined;
+    constructor(message: string, status: number, data?: unknown | undefined);
+}
+/**
+ * Error thrown when authentication is required but not provided,
+ * or when credentials are invalid (HTTP 401).
+ */
+declare class AuthenticationError extends SyftHubError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the user doesn't have permission to access
+ * a resource (HTTP 403).
+ */
+declare class AuthorizationError extends SyftHubError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when a requested resource is not found (HTTP 404).
+ */
+declare class NotFoundError extends SyftHubError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when request validation fails (HTTP 422).
+ * Contains field-level error details when available.
+ */
+declare class ValidationError extends SyftHubError {
+    readonly errors?: Record<string, string[]> | undefined;
+    constructor(message: string, errors?: Record<string, string[]> | undefined);
+}
+/**
+ * Error thrown when a network request fails (connection errors, timeouts).
+ */
+declare class NetworkError extends SyftHubError {
+    readonly cause?: Error | undefined;
+    constructor(message?: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when SDK configuration is invalid.
+ */
+declare class ConfigurationError extends SyftHubError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when username or email already exists in SyftHub (HTTP 409).
+ *
+ * This error indicates a duplicate user registration attempt.
+ * The `field` property indicates which field caused the conflict.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.auth.register({ username: "john", email: "john@example.com", ... });
+ * } catch (error) {
+ *   if (error instanceof UserAlreadyExistsError) {
+ *     console.log(`${error.field} is already taken`);
+ *   }
+ * }
+ * ```
+ */
+declare class UserAlreadyExistsError extends SyftHubError {
+    readonly detail?: unknown | undefined;
+    /** The field that caused the conflict ("username" or "email") */
+    readonly field?: string;
+    constructor(message?: string, detail?: unknown | undefined);
+}
+/**
+ * Error thrown when email already exists in the accounting service during registration.
+ *
+ * This error indicates that the user needs to provide their existing
+ * accounting password to link their SyftHub account with their existing
+ * accounting account.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.auth.register({ username: "john", email: "john@example.com", ... });
+ * } catch (error) {
+ *   if (error instanceof AccountingAccountExistsError) {
+ *     // Prompt user for their existing accounting password
+ *     const accountingPassword = prompt("Enter your existing accounting password:");
+ *     // Retry registration with the password
+ *     await client.auth.register({
+ *       username: "john",
+ *       email: "john@example.com",
+ *       ...,
+ *       accountingPassword
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare class AccountingAccountExistsError extends SyftHubError {
+    readonly detail?: unknown | undefined;
+    /** Indicates that the user needs to provide their existing accounting password */
+    readonly requiresAccountingPassword = true;
+    constructor(message?: string, detail?: unknown | undefined);
+}
+/**
+ * Error thrown when the provided accounting password is invalid.
+ */
+declare class InvalidAccountingPasswordError extends SyftHubError {
+    readonly detail?: unknown | undefined;
+    constructor(message?: string, detail?: unknown | undefined);
+}
+/**
+ * Error thrown when the accounting service is unavailable or returns an error.
+ */
+declare class AccountingServiceUnavailableError extends SyftHubError {
+    readonly detail?: unknown | undefined;
+    constructor(message?: string, detail?: unknown | undefined);
+}
+
+/**
+ * Chat resource for RAG-augmented conversations via the Aggregator service.
+ *
+ * This resource handles satellite token authentication automatically:
+ * - Resolves endpoints and extracts owner information
+ * - Exchanges Hub access tokens for satellite tokens (one per unique owner)
+ * - Sends tokens to the aggregator for forwarding to SyftAI-Space
+ *
+ * @example
+ * // Simple chat completion
+ * const response = await client.chat.complete({
+ *   prompt: 'What is machine learning?',
+ *   model: 'alice/gpt-model',
+ *   dataSources: ['bob/ml-docs'],
+ * });
+ * console.log(response.response);
+ *
+ * // Streaming chat
+ * for await (const event of client.chat.stream(options)) {
+ *   if (event.type === 'token') {
+ *     process.stdout.write(event.content);
+ *   }
+ * }
+ */
+
+/**
+ * Error thrown when the aggregator service is unavailable or returns an error.
+ */
+declare class AggregatorError extends SyftHubError {
+    readonly status?: number | undefined;
+    readonly detail?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, detail?: unknown | undefined);
+}
+/**
+ * Error thrown when an endpoint cannot be resolved.
+ */
+declare class EndpointResolutionError extends SyftHubError {
+    readonly endpointPath?: string | undefined;
+    constructor(message: string, endpointPath?: string | undefined);
+}
+/**
+ * Chat resource for RAG-augmented conversations via the Aggregator.
+ *
+ * This resource provides high-level chat functionality that:
+ * - Queries data sources for relevant context (retrieval)
+ * - Sends prompts with context to model endpoints (generation)
+ * - Supports both synchronous and streaming responses
+ */
+declare class ChatResource {
+    private readonly hub;
+    private readonly auth;
+    private readonly aggregatorUrl;
+    constructor(hub: HubResource, auth: AuthResource, aggregatorUrl: string);
+    /**
+     * Convert any endpoint format to EndpointRef with URL and owner info.
+     * The ownerUsername is critical for satellite token authentication.
+     */
+    private resolveEndpointRef;
+    /**
+     * Collect unique owner usernames from all endpoints.
+     * Used to determine which satellite tokens need to be fetched.
+     */
+    private collectUniqueOwners;
+    /**
+     * Get satellite tokens for all unique endpoint owners.
+     * Returns a map of owner username to satellite token.
+     */
+    private getSatelliteTokensForOwners;
+    /**
+     * Get transaction tokens for all unique endpoint owners.
+     * Returns a map of owner username to transaction token.
+     *
+     * Transaction tokens are used for billing - they authorize the endpoint
+     * owner to charge the current user for usage.
+     */
+    private getTransactionTokensForOwners;
+    /**
+     * Type guard for EndpointRef.
+     */
+    private isEndpointRef;
+    /**
+     * Type guard for EndpointPublic.
+     */
+    private isEndpointPublic;
+    /**
+     * Build the request body for the aggregator.
+     * Includes endpoint_tokens mapping for satellite token authentication.
+     * Includes transaction_tokens mapping for billing authorization.
+     * User identity is derived from satellite tokens, not passed in request body.
+     */
+    private buildRequestBody;
+    /**
+     * Parse a SourceInfo from raw data.
+     */
+    private parseSourceInfo;
+    /**
+     * Parse ChatMetadata from raw data.
+     */
+    private parseMetadata;
+    /**
+     * Parse TokenUsage from raw data.
+     */
+    private parseUsage;
+    /**
+     * Parse document sources from raw data.
+     * The new format is a dict mapping document title to {slug, content}.
+     */
+    private parseDocumentSources;
+    /**
+     * Parse retrieval info (SourceInfo array) from raw data.
+     */
+    private parseRetrievalInfo;
+    /**
+     * Send a chat request and get the complete response.
+     *
+     * This method automatically:
+     * 1. Resolves endpoints and extracts owner information
+     * 2. Exchanges Hub tokens for satellite tokens (one per unique owner)
+     * 3. Fetches transaction tokens for billing authorization
+     * 4. Sends tokens to the aggregator for forwarding to SyftAI-Space
+     *
+     * @param options - Chat completion options
+     * @returns ChatResponse with response text, sources, and metadata
+     * @throws {EndpointResolutionError} If endpoint cannot be resolved
+     * @throws {AggregatorError} If aggregator service fails
+     */
+    complete(options: ChatOptions): Promise<ChatResponse>;
+    /**
+     * Send a chat request and stream response events.
+     *
+     * This method automatically:
+     * 1. Resolves endpoints and extracts owner information
+     * 2. Exchanges Hub tokens for satellite tokens (one per unique owner)
+     * 3. Fetches transaction tokens for billing authorization
+     * 4. Sends tokens to the aggregator for forwarding to SyftAI-Space
+     *
+     * @param options - Chat completion options
+     * @yields ChatStreamEvent objects as they arrive
+     */
+    stream(options: ChatOptions): AsyncGenerator<ChatStreamEvent, void, unknown>;
+    /**
+     * Parse an SSE event into a typed event object.
+     */
+    private parseSSEEvent;
+    /**
+     * Get model endpoints that have connection URLs configured.
+     *
+     * @param limit - Maximum number of results (default: 20)
+     * @returns Array of EndpointPublic objects for models with URLs
+     */
+    getAvailableModels(limit?: number): Promise<EndpointPublic[]>;
+    /**
+     * Get data source endpoints that have connection URLs configured.
+     *
+     * @param limit - Maximum number of results (default: 20)
+     * @returns Array of EndpointPublic objects for data sources with URLs
+     */
+    getAvailableDataSources(limit?: number): Promise<EndpointPublic[]>;
+}
+
+/**
+ * SyftAI-Space resource for direct endpoint queries.
+ *
+ * This module provides low-level access to SyftAI-Space endpoints, allowing
+ * users to build custom RAG pipelines or bypass the aggregator service.
+ *
+ * @example
+ * // Query a data source directly
+ * const docs = await client.syftai.queryDataSource({
+ *   endpoint: { url: 'http://syftai:8080', slug: 'docs' },
+ *   query: 'What is machine learning?',
+ *   userEmail: 'alice@example.com',
+ * });
+ *
+ * // Query a model directly
+ * const response = await client.syftai.queryModel({
+ *   endpoint: { url: 'http://syftai:8080', slug: 'gpt-model' },
+ *   messages: [
+ *     { role: 'system', content: 'You are a helpful assistant.' },
+ *     { role: 'user', content: 'Hello!' },
+ *   ],
+ *   userEmail: 'alice@example.com',
+ * });
+ */
+
+/**
+ * Error thrown when data source retrieval fails.
+ */
+declare class RetrievalError extends SyftHubError {
+    readonly sourcePath?: string | undefined;
+    readonly detail?: unknown | undefined;
+    constructor(message: string, sourcePath?: string | undefined, detail?: unknown | undefined);
+}
+/**
+ * Error thrown when model generation fails.
+ */
+declare class GenerationError extends SyftHubError {
+    readonly modelSlug?: string | undefined;
+    readonly detail?: unknown | undefined;
+    constructor(message: string, modelSlug?: string | undefined, detail?: unknown | undefined);
+}
+/**
+ * Low-level resource for direct SyftAI-Space endpoint queries.
+ *
+ * This resource provides direct access to SyftAI-Space endpoints without
+ * going through the aggregator. Use this when you need:
+ * - Custom RAG pipelines with specific retrieval strategies
+ * - Direct model queries without data source context
+ * - Fine-grained control over the query process
+ *
+ * For most use cases, prefer the higher-level `client.chat` API instead.
+ */
+declare class SyftAIResource {
+    /**
+     * Build headers for SyftAI-Space request.
+     */
+    private buildHeaders;
+    /**
+     * Query a data source endpoint directly.
+     *
+     * @param options - Query options
+     * @returns Array of Document objects
+     * @throws {RetrievalError} If the query fails
+     */
+    queryDataSource(options: QueryDataSourceOptions): Promise<Document[]>;
+    /**
+     * Query a model endpoint directly.
+     *
+     * @param options - Query options
+     * @returns Generated response text
+     * @throws {GenerationError} If generation fails
+     */
+    queryModel(options: QueryModelOptions): Promise<string>;
+    /**
+     * Stream a model response directly.
+     *
+     * @param options - Query options
+     * @yields Response text chunks as they arrive
+     * @throws {GenerationError} If generation fails
+     */
+    queryModelStream(options: QueryModelOptions): AsyncGenerator<string, void, unknown>;
+}
+
+/**
+ * Configuration options for SyftHubClient.
+ */
+interface SyftHubClientOptions {
+    /**
+     * Base URL for the SyftHub API.
+     * Falls back to SYFTHUB_URL environment variable.
+     * @example 'https://hub.syft.com'
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Base URL for the aggregator service (optional).
+     * Falls back to SYFTHUB_AGGREGATOR_URL environment variable.
+     * Defaults to {baseUrl}/aggregator/api/v1
+     */
+    aggregatorUrl?: string;
+    /**
+     * Base URL for the accounting service (optional).
+     * Falls back to SYFTHUB_ACCOUNTING_URL environment variable.
+     */
+    accountingUrl?: string;
+    /**
+     * Email for accounting service authentication (optional).
+     * Falls back to SYFTHUB_ACCOUNTING_EMAIL environment variable.
+     */
+    accountingEmail?: string;
+    /**
+     * Password for accounting service authentication (optional).
+     * Falls back to SYFTHUB_ACCOUNTING_PASSWORD environment variable.
+     */
+    accountingPassword?: string;
+}
+/**
+ * SyftHub SDK client for interacting with the SyftHub API.
+ *
+ * @example
+ * // Basic usage
+ * import { SyftHubClient } from '@syfthub/sdk';
+ *
+ * const client = new SyftHubClient({ baseUrl: 'https://hub.syft.com' });
+ *
+ * // Or use environment variable
+ * // Set SYFTHUB_URL=https://hub.syft.com
+ * const client = new SyftHubClient();
+ *
+ * @example
+ * // Authentication
+ * const user = await client.auth.login('alice', 'password123');
+ * console.log(`Logged in as ${user.username}`);
+ *
+ * // Get current user
+ * const me = await client.auth.me();
+ *
+ * @example
+ * // Browse endpoints
+ * for await (const endpoint of client.hub.browse()) {
+ *   console.log(endpoint.name);
+ * }
+ *
+ * @example
+ * // Manage your endpoints
+ * const endpoint = await client.myEndpoints.create({
+ *   name: 'My Model',
+ *   type: 'model',
+ *   visibility: 'public',
+ * });
+ *
+ * @example
+ * // Token persistence
+ * const tokens = client.getTokens();
+ * // Save tokens to storage...
+ *
+ * // Later, restore tokens
+ * client.setTokens(savedTokens);
+ */
+declare class SyftHubClient {
+    private readonly http;
+    private readonly options;
+    private readonly aggregatorUrl;
+    private _auth?;
+    private _users?;
+    private _myEndpoints?;
+    private _hub?;
+    private _accounting?;
+    private _chat?;
+    private _syftai?;
+    /**
+     * Create a new SyftHub client.
+     *
+     * @param options - Configuration options
+     * @throws {SyftHubError} If baseUrl is not provided and SYFTHUB_URL is not set (in non-browser environments)
+     */
+    constructor(options?: SyftHubClientOptions);
+    /**
+     * Authentication resource for login, register, and session management.
+     *
+     * @example
+     * const user = await client.auth.login('alice', 'password');
+     * await client.auth.logout();
+     */
+    get auth(): AuthResource;
+    /**
+     * Users resource for profile management.
+     *
+     * @example
+     * const user = await client.users.update({ fullName: 'Alice Smith' });
+     * const available = await client.users.checkUsername('newname');
+     */
+    get users(): UsersResource;
+    /**
+     * My Endpoints resource for managing your own endpoints.
+     *
+     * @example
+     * const endpoints = await client.myEndpoints.list().all();
+     * const endpoint = await client.myEndpoints.create({ name: 'My API', type: 'model' });
+     */
+    get myEndpoints(): MyEndpointsResource;
+    /**
+     * Hub resource for browsing public endpoints.
+     *
+     * @example
+     * for await (const endpoint of client.hub.browse()) {
+     *   console.log(endpoint.name);
+     * }
+     */
+    get hub(): HubResource;
+    /**
+     * Accounting resource for billing and transactions.
+     *
+     * The accounting service is external and uses separate credentials
+     * (email/password Basic auth) from SyftHub's JWT authentication.
+     *
+     * Credentials can be provided via:
+     * - Constructor options: accountingUrl, accountingEmail, accountingPassword
+     * - Environment variables: SYFTHUB_ACCOUNTING_URL, SYFTHUB_ACCOUNTING_EMAIL, SYFTHUB_ACCOUNTING_PASSWORD
+     *
+     * @throws {SyftHubError} If accounting credentials are not configured
+     *
+     * @example
+     * const user = await client.accounting.getUser();
+     * console.log(`Balance: ${user.balance}`);
+     *
+     * // Create a transaction
+     * const tx = await client.accounting.createTransaction({
+     *   recipientEmail: 'bob@example.com',
+     *   amount: 10.0
+     * });
+     */
+    get accounting(): AccountingResource;
+    /**
+     * Chat resource for RAG-augmented conversations via the Aggregator.
+     *
+     * This resource provides high-level chat functionality that integrates
+     * with the SyftHub Aggregator service for RAG workflows.
+     *
+     * @example
+     * // Simple chat completion
+     * const response = await client.chat.complete({
+     *   prompt: 'What is machine learning?',
+     *   model: 'alice/gpt-model',
+     *   dataSources: ['bob/ml-docs'],
+     * });
+     * console.log(response.response);
+     *
+     * // Streaming chat
+     * for await (const event of client.chat.stream(options)) {
+     *   if (event.type === 'token') {
+     *     process.stdout.write(event.content);
+     *   }
+     * }
+     *
+     * // Get available endpoints
+     * const models = await client.chat.getAvailableModels();
+     * const sources = await client.chat.getAvailableDataSources();
+     */
+    get chat(): ChatResource;
+    /**
+     * SyftAI-Space resource for direct endpoint queries (low-level API).
+     *
+     * This resource provides direct access to SyftAI-Space endpoints without
+     * going through the aggregator. Use this when you need custom RAG pipelines
+     * or fine-grained control over queries.
+     *
+     * For most use cases, prefer the higher-level `client.chat` API instead.
+     *
+     * @example
+     * // Query a data source directly
+     * const docs = await client.syftai.queryDataSource({
+     *   endpoint: { url: 'http://syftai:8080', slug: 'docs' },
+     *   query: 'What is Python?',
+     *   userEmail: 'alice@example.com',
+     * });
+     *
+     * // Query a model directly
+     * const response = await client.syftai.queryModel({
+     *   endpoint: { url: 'http://syftai:8080', slug: 'gpt-model' },
+     *   messages: [{ role: 'user', content: 'Hello!' }],
+     *   userEmail: 'alice@example.com',
+     * });
+     */
+    get syftai(): SyftAIResource;
+    /**
+     * Get current authentication tokens.
+     *
+     * Use this to persist tokens for later sessions.
+     *
+     * @returns Current tokens or null if not authenticated
+     *
+     * @example
+     * const tokens = client.getTokens();
+     * if (tokens) {
+     *   localStorage.setItem('tokens', JSON.stringify(tokens));
+     * }
+     */
+    getTokens(): AuthTokens | null;
+    /**
+     * Set authentication tokens.
+     *
+     * Use this to restore a session from previously saved tokens.
+     *
+     * @param tokens - Tokens to set
+     *
+     * @example
+     * const saved = JSON.parse(localStorage.getItem('tokens'));
+     * if (saved) {
+     *   client.setTokens(saved);
+     * }
+     */
+    setTokens(tokens: AuthTokens): void;
+    /**
+     * Check if the client is currently authenticated.
+     *
+     * @returns True if tokens are present
+     */
+    get isAuthenticated(): boolean;
+    /**
+     * Check if accounting service is configured.
+     *
+     * Use this to check if accounting credentials are available before
+     * accessing the `accounting` property, which will throw if not configured.
+     *
+     * @returns True if accounting url, email, and password are all configured
+     *
+     * @example
+     * if (client.isAccountingConfigured) {
+     *   const user = await client.accounting.getUser();
+     * }
+     */
+    get isAccountingConfigured(): boolean;
+    /**
+     * Close the client and clean up resources.
+     *
+     * Currently a no-op, but may be used in future for connection pooling.
+     */
+    close(): void;
+}
+
+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 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 };