@syfthub/sdk 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -792,7 +792,15 @@ interface Document {
 /**
  * Status of a data source query.
  */
-type SourceStatus = 'success' | 'error' | 'timeout';
+type SourceStatus = 'success' | 'error' | 'timeout' | 'payment_failed' | 'access_denied' | 'policy_violation' | 'rate_limited';
+/**
+ * Machine-readable rejection reason on a {@link BillingEntry}.
+ *
+ * The known set the producer emits today. `BillingEntry.reasonCode` stays open
+ * (`ReasonCode | (string & {})`) so a future code never breaks typing, while
+ * still offering autocomplete on the known values.
+ */
+type ReasonCode = 'NO_PRICING_TIER' | 'INSUFFICIENT_BALANCE' | 'PAYMENT_REQUIRED' | 'ACCESS_DENIED' | 'RATE_LIMITED';
 /**
  * Information about a data source retrieval (metadata).
  */
@@ -838,6 +846,101 @@ interface TokenUsage {
     /** Total tokens used */
     totalTokens: number;
 }
+/**
+ * The "to whom" of a billing entry — the endpoint owner / publisher.
+ *
+ * All fields are optional; `walletAddress` is a public MPP address only and
+ * never a private key.
+ */
+interface Recipient {
+    /** Endpoint owner / publisher username */
+    username?: string;
+    /** Recipient email */
+    email?: string;
+    /** Public MPP wallet address (never a private key) */
+    walletAddress?: string;
+}
+/**
+ * A rail-native transaction reference for a billing entry.
+ *
+ * `id` is the rail-native identifier (Tempo tx hash for `mpp`; the ledger
+ * transaction id for `xendit` / `stripe`); `rail` is the discriminator.
+ */
+interface Transaction {
+    /** Payment rail discriminator (mpp, xendit, stripe, ...) */
+    rail: string;
+    /** Rail-native transaction id */
+    id: string;
+    /** Secondary reference (e.g. MPP external_id) */
+    reference?: string;
+}
+/**
+ * A single policy-metadata entry from a queried source.
+ *
+ * Emitted by both payment and non-payment policies. When surfaced via the
+ * aggregated {@link Billing} block, `source` carries the `owner/slug` of the
+ * source that produced the entry; on the direct path it is absent.
+ */
+interface BillingEntry {
+    /** Source endpoint path (owner/slug); absent if direct */
+    source?: string;
+    /** Policy type (e.g. mpp_per_request, rate_limit, pii_filter) */
+    policyType: string;
+    /** Policy kind (payment, access, transform, rate_limit) */
+    kind: string;
+    /** Outcome status (charged, refunded, free, rejected, applied, skipped) */
+    status: string;
+    /** Charged amount, if any */
+    amount?: number;
+    /** Currency code, if any */
+    currency?: string;
+    /** Who the payment is owed to, if any */
+    recipient?: Recipient;
+    /** Rail-native transaction reference, if any */
+    transaction?: Transaction;
+    /** Machine-readable rejection code; see {@link ReasonCode} for the known set */
+    reasonCode?: ReasonCode | (string & {});
+    /** Human-readable reason message */
+    reason?: string;
+    /** Extra structured details (e.g. { documents: 3 }) */
+    details: Record<string, unknown>;
+}
+/**
+ * Aggregated billing block surfaced on chat and search responses.
+ *
+ * `totalCost` is the sum of entries with `status === "charged"` (null if none
+ * charged); `currency` is the common currency or null if mixed. No FX
+ * conversion is performed — each entry keeps its own currency.
+ */
+interface Billing {
+    /**
+     * Sum of charged entries; null if nothing charged.
+     *
+     * Note: can be > 0 on a *rejected* query — an earlier policy may have
+     * committed a charge before a later policy blocked the request (the
+     * rejection carries both the `charged` and the `rejected` entry). Inspect
+     * per-entry `status` rather than assuming a positive `totalCost` means success.
+     */
+    totalCost: number | null;
+    /** Common currency, or null if mixed */
+    currency: string | null;
+    /** Per-source policy-metadata entries */
+    entries: BillingEntry[];
+}
+/**
+ * Raw policy-metadata block returned on the direct syft-space path.
+ *
+ * Unlike the aggregated {@link Billing} block, this is the per-source object
+ * exactly as the syft-space `/query` response carries it: an `outcome` string
+ * plus the list of {@link BillingEntry} items (whose `source` key is absent on
+ * the direct path). No aggregation or total is applied.
+ */
+interface PolicyMetadata {
+    /** Query outcome (e.g. success, payment_required) */
+    outcome: string;
+    /** Per-policy metadata entries */
+    entries: BillingEntry[];
+}
 /**
  * Response from a chat completion request.
  */
@@ -854,6 +957,8 @@ interface ChatResponse {
     usage?: TokenUsage;
     /** Normalized contribution scores per source (owner/slug to fraction 0-1) */
     profitShare?: Record<string, number>;
+    /** Aggregated payment-policy metadata across queried sources */
+    billing?: Billing;
 }
 /**
  * A chat message for model queries.
@@ -895,6 +1000,73 @@ interface ChatOptions {
     /** Conversation history (prior turns) for multi-turn context */
     messages?: Message[];
 }
+/**
+ * A single document returned by a retrieval-only search.
+ *
+ * Unlike {@link Document} (the low-level direct-query shape), this carries the
+ * document title and the source endpoint path, matching the aggregated
+ * `sources` map returned by the aggregator's retrieval-only path.
+ */
+interface SearchDocument {
+    /** Document title (key in the sources map) */
+    title: string;
+    /** Source endpoint path (owner/slug) the document came from */
+    slug: string;
+    /** The document content */
+    content: string;
+}
+/**
+ * Options for a retrieval-only search via the Aggregator.
+ *
+ * Symmetric to {@link ChatOptions} minus the model: data sources are queried
+ * for relevant documents, but no model is invoked.
+ */
+interface SearchQueryOptions {
+    /** The search query */
+    prompt: string;
+    /** Data source endpoints (paths, EndpointRefs, or `collective/<slug>` paths) */
+    dataSources?: (string | EndpointRef)[];
+    /** Number of documents to retrieve per source (default: 5) */
+    topK?: number;
+    /** Minimum similarity for retrieved docs (default: 0.5) */
+    similarityThreshold?: number;
+    /** Custom aggregator URL to use instead of the default */
+    aggregatorUrl?: string;
+    /** Use guest mode for unauthenticated access to policy-free endpoints */
+    guestMode?: boolean;
+    /** AbortSignal for request cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Response from a retrieval-only search via the Aggregator.
+ *
+ * Mirrors {@link ChatResponse} minus the generated text: retrieval runs across
+ * the data sources (with satellite-token auth and MPP payment handled by the
+ * aggregator), but no model is invoked.
+ */
+interface SearchResponse {
+    /** Retrieved documents across all data sources */
+    documents: SearchDocument[];
+    /** Metadata about each data source retrieval (status, count, errors) */
+    retrievalInfo: SourceInfo[];
+    /** Timing metadata */
+    metadata: ChatMetadata;
+    /** Aggregated payment-policy metadata across queried sources */
+    billing?: Billing;
+}
+/**
+ * Result of a direct data-source query (`client.syftai.queryDataSource`).
+ *
+ * Carries the retrieved documents plus the raw `policyMetadata` block from the
+ * syft-space `/query` response (Boundary A), so direct-query callers get the
+ * same authoritative payment/policy metadata the aggregator surfaces.
+ */
+interface DataSourceQueryResult {
+    /** Retrieved documents */
+    documents: Document[];
+    /** Raw policy metadata from the syft-space response, if present */
+    policyMetadata?: PolicyMetadata;
+}
 /**
  * Options for querying a data source directly.
  */
@@ -909,6 +1081,22 @@ interface QueryDataSourceOptions {
     topK?: number;
     /** Minimum similarity score (default: 0.5) */
     similarityThreshold?: number;
+    /**
+     * Pre-minted satellite token to send as `Authorization: Bearer`. If omitted,
+     * one is minted automatically when an owner is known (see `ownerUsername` /
+     * `endpoint.ownerUsername`).
+     */
+    authorizationToken?: string;
+    /**
+     * Endpoint owner username used as the satellite-token audience. Falls back to
+     * `endpoint.ownerUsername`.
+     */
+    ownerUsername?: string;
+    /**
+     * If true, settle an MPP `402 Payment Required` challenge via the Hub wallet
+     * and retry. If false (default), a `402` throws a `RetrievalError`.
+     */
+    pay?: boolean;
 }
 /**
  * Options for querying a model directly.
@@ -1003,6 +1191,8 @@ interface DoneEvent {
     usage?: TokenUsage;
     /** Normalized contribution scores per source (owner/slug to fraction 0-1) */
     profitShare?: Record<string, number>;
+    /** Aggregated payment-policy metadata across queried sources */
+    billing?: Billing;
     /**
      * Clean response text with attribution markers stripped.
      * Present when attribution ran (data sources were used). Frontends should
@@ -1016,6 +1206,11 @@ interface DoneEvent {
 interface ErrorEvent {
     type: 'error';
     message: string;
+    /**
+     * Billing surfaced on the error path: a paid query may be REJECTED yet still
+     * carry policy/billing metadata (e.g. a charge that must be refunded).
+     */
+    billing?: Billing;
 }
 /**
  * Discriminated union of all streaming event types.
@@ -1039,6 +1234,131 @@ interface ErrorEvent {
  */
 type ChatStreamEvent = RetrievalStartEvent | SourceCompleteEvent | RetrievalCompleteEvent | RerankingStartEvent | RerankingCompleteEvent | GenerationStartEvent | GenerationHeartbeatEvent | TokenEvent$1 | DoneEvent | ErrorEvent;
 
+/**
+ * Resource for managing user's aggregator configurations.
+ *
+ * Aggregators are custom RAG orchestration service endpoints that users can
+ * configure to use for chat operations. Each user can have multiple aggregator
+ * configurations, with one set as the default.
+ *
+ * The first aggregator created is automatically set as the default. Only one
+ * aggregator can be the default at a time; setting a new default automatically
+ * unsets the previous one.
+ *
+ * @example
+ * // List all aggregators
+ * const aggregators = await client.users.aggregators.list();
+ * for (const agg of aggregators) {
+ *   console.log(`${agg.name}: ${agg.url}`);
+ * }
+ *
+ * @example
+ * // Create a new aggregator
+ * const agg = await client.users.aggregators.create({
+ *   name: 'My Custom Aggregator',
+ *   url: 'https://my-aggregator.example.com'
+ * });
+ *
+ * @example
+ * // Set as default
+ * const defaultAgg = await client.users.aggregators.setDefault(agg.id);
+ */
+declare class AggregatorsResource {
+    private readonly http;
+    constructor(http: HTTPClient);
+    /**
+     * List all aggregator configurations for the current user.
+     *
+     * @returns Array of UserAggregator objects
+     * @throws {AuthenticationError} If not authenticated
+     *
+     * @example
+     * const aggregators = await client.users.aggregators.list();
+     * for (const agg of aggregators) {
+     *   if (agg.isDefault) {
+     *     console.log(`Default: ${agg.name}`);
+     *   }
+     * }
+     */
+    list(): Promise<UserAggregator[]>;
+    /**
+     * Get a specific aggregator configuration by ID.
+     *
+     * @param aggregatorId - The aggregator ID
+     * @returns The UserAggregator object
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NotFoundError} If aggregator not found
+     *
+     * @example
+     * const agg = await client.users.aggregators.get(1);
+     * console.log(`${agg.name}: ${agg.url}`);
+     */
+    get(aggregatorId: number): Promise<UserAggregator>;
+    /**
+     * Create a new aggregator configuration.
+     *
+     * The first aggregator created is automatically set as the default.
+     *
+     * @param input - Aggregator creation input
+     * @returns The created UserAggregator object
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {ValidationError} If input is invalid
+     *
+     * @example
+     * const agg = await client.users.aggregators.create({
+     *   name: 'My Custom Aggregator',
+     *   url: 'https://my-aggregator.example.com'
+     * });
+     * console.log(`Created: ${agg.id}`);
+     */
+    create(input: UserAggregatorCreateInput): Promise<UserAggregator>;
+    /**
+     * Update an aggregator configuration.
+     *
+     * Only provided fields will be updated.
+     *
+     * @param aggregatorId - The aggregator ID to update
+     * @param input - Fields to update
+     * @returns The updated UserAggregator object
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NotFoundError} If aggregator not found
+     * @throws {ValidationError} If input is invalid
+     *
+     * @example
+     * const agg = await client.users.aggregators.update(1, {
+     *   name: 'Updated Name'
+     * });
+     */
+    update(aggregatorId: number, input: UserAggregatorUpdateInput): Promise<UserAggregator>;
+    /**
+     * Delete an aggregator configuration.
+     *
+     * @param aggregatorId - The aggregator ID to delete
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NotFoundError} If aggregator not found
+     *
+     * @example
+     * await client.users.aggregators.delete(1);
+     */
+    delete(aggregatorId: number): Promise<void>;
+    /**
+     * Set an aggregator as the default.
+     *
+     * Only one aggregator can be the default at a time. Setting a new default
+     * automatically unsets the previous one.
+     *
+     * @param aggregatorId - The aggregator ID to set as default
+     * @returns The updated UserAggregator object with isDefault=true
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NotFoundError} If aggregator not found
+     *
+     * @example
+     * const agg = await client.users.aggregators.setDefault(2);
+     * console.log(`${agg.name} is now the default`);
+     */
+    setDefault(aggregatorId: number): Promise<UserAggregator>;
+}
+
 /**
  * Authentication resource for login, register, and session management.
  *
@@ -1345,131 +1665,6 @@ interface SatelliteTokenResponse {
     expiresIn: number;
 }
 
-/**
- * Resource for managing user's aggregator configurations.
- *
- * Aggregators are custom RAG orchestration service endpoints that users can
- * configure to use for chat operations. Each user can have multiple aggregator
- * configurations, with one set as the default.
- *
- * The first aggregator created is automatically set as the default. Only one
- * aggregator can be the default at a time; setting a new default automatically
- * unsets the previous one.
- *
- * @example
- * // List all aggregators
- * const aggregators = await client.users.aggregators.list();
- * for (const agg of aggregators) {
- *   console.log(`${agg.name}: ${agg.url}`);
- * }
- *
- * @example
- * // Create a new aggregator
- * const agg = await client.users.aggregators.create({
- *   name: 'My Custom Aggregator',
- *   url: 'https://my-aggregator.example.com'
- * });
- *
- * @example
- * // Set as default
- * const defaultAgg = await client.users.aggregators.setDefault(agg.id);
- */
-declare class AggregatorsResource {
-    private readonly http;
-    constructor(http: HTTPClient);
-    /**
-     * List all aggregator configurations for the current user.
-     *
-     * @returns Array of UserAggregator objects
-     * @throws {AuthenticationError} If not authenticated
-     *
-     * @example
-     * const aggregators = await client.users.aggregators.list();
-     * for (const agg of aggregators) {
-     *   if (agg.isDefault) {
-     *     console.log(`Default: ${agg.name}`);
-     *   }
-     * }
-     */
-    list(): Promise<UserAggregator[]>;
-    /**
-     * Get a specific aggregator configuration by ID.
-     *
-     * @param aggregatorId - The aggregator ID
-     * @returns The UserAggregator object
-     * @throws {AuthenticationError} If not authenticated
-     * @throws {NotFoundError} If aggregator not found
-     *
-     * @example
-     * const agg = await client.users.aggregators.get(1);
-     * console.log(`${agg.name}: ${agg.url}`);
-     */
-    get(aggregatorId: number): Promise<UserAggregator>;
-    /**
-     * Create a new aggregator configuration.
-     *
-     * The first aggregator created is automatically set as the default.
-     *
-     * @param input - Aggregator creation input
-     * @returns The created UserAggregator object
-     * @throws {AuthenticationError} If not authenticated
-     * @throws {ValidationError} If input is invalid
-     *
-     * @example
-     * const agg = await client.users.aggregators.create({
-     *   name: 'My Custom Aggregator',
-     *   url: 'https://my-aggregator.example.com'
-     * });
-     * console.log(`Created: ${agg.id}`);
-     */
-    create(input: UserAggregatorCreateInput): Promise<UserAggregator>;
-    /**
-     * Update an aggregator configuration.
-     *
-     * Only provided fields will be updated.
-     *
-     * @param aggregatorId - The aggregator ID to update
-     * @param input - Fields to update
-     * @returns The updated UserAggregator object
-     * @throws {AuthenticationError} If not authenticated
-     * @throws {NotFoundError} If aggregator not found
-     * @throws {ValidationError} If input is invalid
-     *
-     * @example
-     * const agg = await client.users.aggregators.update(1, {
-     *   name: 'Updated Name'
-     * });
-     */
-    update(aggregatorId: number, input: UserAggregatorUpdateInput): Promise<UserAggregator>;
-    /**
-     * Delete an aggregator configuration.
-     *
-     * @param aggregatorId - The aggregator ID to delete
-     * @throws {AuthenticationError} If not authenticated
-     * @throws {NotFoundError} If aggregator not found
-     *
-     * @example
-     * await client.users.aggregators.delete(1);
-     */
-    delete(aggregatorId: number): Promise<void>;
-    /**
-     * Set an aggregator as the default.
-     *
-     * Only one aggregator can be the default at a time. Setting a new default
-     * automatically unsets the previous one.
-     *
-     * @param aggregatorId - The aggregator ID to set as default
-     * @returns The updated UserAggregator object with isDefault=true
-     * @throws {AuthenticationError} If not authenticated
-     * @throws {NotFoundError} If aggregator not found
-     *
-     * @example
-     * const agg = await client.users.aggregators.setDefault(2);
-     * console.log(`${agg.name} is now the default`);
-     */
-    setDefault(aggregatorId: number): Promise<UserAggregator>;
-}
-
 /**
  * Users resource for profile management and availability checks.
  *
@@ -2565,7 +2760,19 @@ declare class AgentSessionClient {
 declare class AggregatorError extends SyftHubError {
     readonly status?: number | undefined;
     readonly detail?: unknown | undefined;
-    constructor(message: string, status?: number | undefined, detail?: unknown | undefined);
+    /**
+     * Billing/policy metadata the aggregator may attach even on an error
+     * response — a paid query can be REJECTED yet still carry a charge that
+     * must be surfaced (and possibly refunded).
+     */
+    readonly billing?: Billing | undefined;
+    constructor(message: string, status?: number | undefined, detail?: unknown | undefined, 
+    /**
+     * Billing/policy metadata the aggregator may attach even on an error
+     * response — a paid query can be REJECTED yet still carry a charge that
+     * must be surfaced (and possibly refunded).
+     */
+    billing?: Billing | undefined);
 }
 /**
  * Error thrown when an endpoint cannot be resolved.
@@ -2674,6 +2881,20 @@ declare class ChatResource {
      * Parse TokenUsage from raw data.
      */
     private parseUsage;
+    /**
+     * Parse a single billing/policy-metadata entry from a raw (snake_case) dict.
+     *
+     * Shared by {@link parseBilling} (aggregated, carries `source`) and the
+     * direct-path `policy_metadata` parsing in {@link SyftAIResource}.
+     */
+    static parseBillingEntry(raw: Record<string, unknown>): BillingEntry;
+    /**
+     * Parse the aggregated `billing` block from a raw aggregator response.
+     *
+     * Returns undefined when no `billing` object is present (e.g. an error body
+     * with no policy metadata). The wire keys are snake_case.
+     */
+    private parseBilling;
     /**
      * Parse document sources from raw data.
      * The new format is a dict mapping document title to {slug, content}.
@@ -2698,6 +2919,28 @@ declare class ChatResource {
      * @throws {AggregatorError} If aggregator service fails
      */
     complete(options: ChatOptions): Promise<ChatResponse>;
+    /**
+     * Placeholder model for retrieval-only requests. The aggregator requires a
+     * `model` field on every request, but short-circuits before dereferencing it
+     * when `retrieval_only` is set, so an empty ref is never contacted.
+     */
+    private static readonly RETRIEVAL_ONLY_MODEL;
+    /**
+     * Retrieve documents from data sources without model generation.
+     *
+     * Drives the aggregator's retrieval-only path: data sources are queried in
+     * parallel (with satellite-token auth and MPP payment handled server-side,
+     * exactly like {@link complete}), but no model is invoked.
+     *
+     * Prefer the symmetric `client.search.query(...)` facade; this is the
+     * underlying primitive.
+     *
+     * @param options - Search options
+     * @returns SearchResponse with retrieved documents and per-source metadata
+     * @throws {EndpointResolutionError} If a data source cannot be resolved
+     * @throws {AggregatorError} If the aggregator service fails
+     */
+    retrieve(options: SearchQueryOptions): Promise<SearchResponse>;
     /**
      * Send a chat request and stream response events.
      *
@@ -2732,6 +2975,58 @@ declare class ChatResource {
     getAvailableDataSources(limit?: number): Promise<EndpointPublic[]>;
 }
 
+/**
+ * Search resource for retrieval-only queries via the Aggregator service.
+ *
+ * Symmetric counterpart to {@link ChatResource}: where `client.chat.complete()`
+ * retrieves context *and* generates a model response, `client.search.query()`
+ * retrieves documents from data sources without invoking any model.
+ *
+ * @example
+ * // Symmetric to client.chat.complete(...)
+ * const result = await client.search.query({
+ *   prompt: 'What happened at EPFL this week?',
+ *   dataSources: ['epfl-news/epfl-news'],
+ * });
+ * for (const doc of result.documents) {
+ *   console.log(doc.title, '->', doc.content.slice(0, 80));
+ * }
+ *
+ * Authentication and billing are handled by the aggregator exactly as for chat:
+ * satellite tokens are minted per data source owner, and metered endpoints that
+ * respond with `402 Payment Required` are settled via the user's Hub wallet.
+ */
+
+/**
+ * Retrieval-only search via the Aggregator.
+ *
+ * Thin facade over {@link ChatResource.retrieve}, exposed as `client.search` to
+ * mirror the shape of `client.chat`.
+ */
+declare class SearchResource {
+    private readonly chat;
+    /**
+     * @param chat - The chat resource that owns aggregator communication and
+     *   request preparation (satellite tokens, MPP, collective expansion). Search
+     *   reuses it rather than duplicating that logic.
+     */
+    constructor(chat: ChatResource);
+    /**
+     * Retrieve documents from data sources without model generation.
+     *
+     * @param options - Search options (prompt, data sources, top-k, etc.)
+     * @returns SearchResponse with retrieved documents and per-source metadata
+     *
+     * @example
+     * const result = await client.search.query({
+     *   prompt: 'Hello, world!',
+     *   dataSources: ['epfl-news/epfl-news'],
+     * });
+     * console.log(result.documents.length, 'documents');
+     */
+    query(options: SearchQueryOptions): Promise<SearchResponse>;
+}
+
 /**
  * SyftAI-Space resource for direct endpoint queries.
  *
@@ -2785,18 +3080,66 @@ declare class GenerationError extends SyftHubError {
  * For most use cases, prefer the higher-level `client.chat` API instead.
  */
 declare class SyftAIResource {
+    private readonly http;
+    /**
+     * @param http - Hub HTTP client, used to mint satellite tokens and settle
+     *   MPP payments. Endpoint queries themselves use direct `fetch`, since the
+     *   SyftAI-Space URL is arbitrary and not the Hub base URL.
+     */
+    constructor(http: HTTPClient);
+    /**
+     * Mint a satellite token for `audience` (the endpoint owner's username).
+     *
+     * Mirrors the aggregator's token coordination layer: try an authenticated
+     * token first, then fall back to a guest token. Returns `undefined` if both
+     * fail, so the caller can still attempt an unauthenticated request.
+     */
+    private mintSatelliteToken;
+    /**
+     * Pay an MPP `402` challenge via the Hub wallet, returning an X-Payment credential.
+     *
+     * Mirrors the aggregator's `handleMppPayment`: the `WWW-Authenticate`
+     * challenge is forwarded verbatim to the Hub's `/api/v1/wallet/pay`, which
+     * parses it and returns an `x_payment` string to attach to a retry.
+     */
+    private payMpp;
     /**
      * Build headers for SyftAI-Space request.
      */
     private buildHeaders;
+    /**
+     * Parse documents from a SyftAI-Space query response.
+     *
+     * Mirrors the aggregator's `DataSourceClient._parse_syftai_response`: the
+     * canonical shape nests documents under `references.documents` and names the
+     * score `similarity_score`. A legacy top-level `documents` list (with
+     * `score`) is still honoured for backward compatibility.
+     */
+    private parseDocuments;
+    /**
+     * Parse the raw `policy_metadata` block from a syft-space response.
+     *
+     * The direct path (Boundary A) carries a top-level `policy_metadata` object
+     * shaped `{ outcome, entries: [...] }`. Entries reuse the {@link BillingEntry}
+     * shape (with `source` absent), so this delegates entry parsing to
+     * {@link ChatResource.parseBillingEntry}. The wire keys are snake_case.
+     */
+    private parsePolicyMetadata;
     /**
      * Query a data source endpoint directly.
      *
+     * Authentication mirrors the aggregator: SyftAI-Space endpoints expect a
+     * satellite bearer token whose audience is the endpoint owner's username. If
+     * `authorizationToken` is not supplied, one is minted automatically when an
+     * owner is known (`ownerUsername` option or `endpoint.ownerUsername`).
+     *
      * @param options - Query options
-     * @returns Array of Document objects
+     * @returns DataSourceQueryResult — the retrieved documents plus the raw
+     *   `policyMetadata` block from the syft-space response (price, recipient,
+     *   transaction, status).
      * @throws {RetrievalError} If the query fails
      */
-    queryDataSource(options: QueryDataSourceOptions): Promise<Document[]>;
+    queryDataSource(options: QueryDataSourceOptions): Promise<DataSourceQueryResult>;
     /**
      * Query a model endpoint directly.
      *
@@ -2895,8 +3238,10 @@ declare class SyftHubClient {
     private _myEndpoints?;
     private _hub?;
     private _accounting?;
+    private _aggregators?;
     private _agent?;
     private _chat?;
+    private _search?;
     private _syftai?;
     private _apiTokens?;
     /**
@@ -2976,22 +3321,8 @@ declare class SyftHubClient {
      */
     get accounting(): AccountingResource;
     /**
-     * Initialize the accounting (wallet) resource.
-     *
-     * The wallet API uses the same SyftHub authentication as other resources.
-     * This method simply verifies authentication and creates the resource.
-     *
-     * @returns The initialized AccountingResource
-     * @throws {AuthenticationError} If not authenticated
-     *
-     * @example
-     * // Login first, then initialize accounting
-     * await client.auth.login('alice', 'password');
-     * await client.initAccounting();
-     *
-     * // Now accounting is available
-     * const wallet = await client.accounting.getWallet();
-     * const balance = await client.accounting.getBalance();
+     * @deprecated Accounting is now initialized automatically on first access.
+     * This method is kept for backward compatibility and is a no-op.
      */
     initAccounting(): Promise<AccountingResource>;
     /**
@@ -3021,6 +3352,23 @@ declare class SyftHubClient {
      * const sources = await client.chat.getAvailableDataSources();
      */
     get chat(): ChatResource;
+    /**
+     * Retrieval-only search via the Aggregator (no model generation).
+     *
+     * Symmetric counterpart to {@link chat}: queries data sources for relevant
+     * documents without invoking a model. Satellite-token auth and MPP payment
+     * are handled by the aggregator exactly as for chat.
+     *
+     * @example
+     * const result = await client.search.query({
+     *   prompt: 'Hello, world!',
+     *   dataSources: ['epfl-news/epfl-news'],
+     * });
+     * for (const doc of result.documents) {
+     *   console.log(doc.title, doc.content.slice(0, 80));
+     * }
+     */
+    get search(): SearchResource;
     /**
      * SyftAI-Space resource for direct endpoint queries (low-level API).
      *
@@ -3066,6 +3414,7 @@ declare class SyftHubClient {
      * // Revoke a token
      * await client.apiTokens.revoke(tokenId);
      */
+    get aggregators(): AggregatorsResource;
     get apiTokens(): APITokensResource;
     /**
      * Check if the client is using API token authentication.
@@ -3129,4 +3478,4 @@ declare class SyftHubClient {
     close(): void;
 }
 
-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 };
+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 Billing, type BillingEntry, type BrowseOptions, type ChatMetadata, type ChatOptions, ChatResource, type ChatResponse, type ChatStreamEvent, ConfigurationError, type Connection, type CreateAPITokenInput, type DataSourceQueryResult, 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 PolicyMetadata, type QueryDataSourceOptions, type QueryModelOptions, type ReasonCode, type Recipient, type RegisterResult, type RetrievalCompleteEvent, RetrievalError, type RetrievalStartEvent, type SearchDocument, type SearchQueryOptions, SearchResource, type SearchResponse, type SourceCompleteEvent, type SourceInfo, type SourceStatus, SyftAIResource, SyftHubClient, type SyftHubClientOptions, SyftHubError, type SyncEndpointsResponse, type TokenEvent$1 as TokenEvent, type Transaction, 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 };