@syfthub/sdk 0.2.1 → 0.3.1

package/dist/index.cjs

@@ -679,6 +679,116 @@ var APITokensResource = class {
   }
 };
 
+// src/resources/aggregators.ts
+var AggregatorsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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}`);
+   *   }
+   * }
+   */
+  async list() {
+    return this.http.get("/api/v1/users/me/aggregators");
+  }
+  /**
+   * 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}`);
+   */
+  async get(aggregatorId) {
+    return this.http.get(`/api/v1/users/me/aggregators/${aggregatorId}`);
+  }
+  /**
+   * 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}`);
+   */
+  async create(input) {
+    return this.http.post("/api/v1/users/me/aggregators", input);
+  }
+  /**
+   * 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'
+   * });
+   */
+  async update(aggregatorId, input) {
+    return this.http.put(`/api/v1/users/me/aggregators/${aggregatorId}`, input);
+  }
+  /**
+   * 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);
+   */
+  async delete(aggregatorId) {
+    await this.http.delete(`/api/v1/users/me/aggregators/${aggregatorId}`);
+  }
+  /**
+   * 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`);
+   */
+  async setDefault(aggregatorId) {
+    return this.http.patch(`/api/v1/users/me/aggregators/${aggregatorId}/default`);
+  }
+};
+
 // src/resources/auth.ts
 init_errors();
 var AuthResource = class {
@@ -1066,116 +1176,6 @@ var AuthResource = class {
   }
 };
 
-// src/resources/aggregators.ts
-var AggregatorsResource = class {
-  constructor(http) {
-    this.http = http;
-  }
-  /**
-   * 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}`);
-   *   }
-   * }
-   */
-  async list() {
-    return this.http.get("/api/v1/users/me/aggregators");
-  }
-  /**
-   * 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}`);
-   */
-  async get(aggregatorId) {
-    return this.http.get(`/api/v1/users/me/aggregators/${aggregatorId}`);
-  }
-  /**
-   * 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}`);
-   */
-  async create(input) {
-    return this.http.post("/api/v1/users/me/aggregators", input);
-  }
-  /**
-   * 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'
-   * });
-   */
-  async update(aggregatorId, input) {
-    return this.http.put(`/api/v1/users/me/aggregators/${aggregatorId}`, input);
-  }
-  /**
-   * 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);
-   */
-  async delete(aggregatorId) {
-    await this.http.delete(`/api/v1/users/me/aggregators/${aggregatorId}`);
-  }
-  /**
-   * 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`);
-   */
-  async setDefault(aggregatorId) {
-    return this.http.patch(`/api/v1/users/me/aggregators/${aggregatorId}/default`);
-  }
-};
-
 // src/resources/users.ts
 var UsersResource = class {
   constructor(http) {
@@ -2189,10 +2189,11 @@ function getEndpointPublicPath(endpoint) {
 
 // src/resources/chat.ts
 var AggregatorError = class extends exports.SyftHubError {
-  constructor(message, status, detail) {
+  constructor(message, status, detail, billing) {
     super(message);
     this.status = status;
     this.detail = detail;
+    this.billing = billing;
     this.name = "AggregatorError";
   }
 };
@@ -2398,7 +2399,7 @@ var ChatResource = class _ChatResource {
    * Resolves endpoints, fetches tokens, and builds the aggregator request body.
    * Returns the request body and the resolved aggregator URL.
    */
-  async prepareRequest(options, stream) {
+  async prepareRequest(options, stream, retrievalOnly = false) {
     const modelRef = await this.resolveEndpointRef(options.model, "model");
     const expandedDataSources = await this.expandCollectivePaths(options.dataSources ?? []);
     const dsRefs = [];
@@ -2433,7 +2434,8 @@ var ChatResource = class _ChatResource {
         stream,
         messages: options.messages,
         peerToken,
-        peerChannel
+        peerChannel,
+        retrievalOnly
       }
     );
     const effectiveAggregatorUrl = (options.aggregatorUrl ?? this.aggregatorUrl).replace(
@@ -2447,12 +2449,14 @@ var ChatResource = class _ChatResource {
    */
   async handleAggregatorErrorResponse(response) {
     let message = `HTTP ${response.status}`;
+    let billing;
     try {
       const data = await response.json();
-      message = String(data["message"] ?? data["error"] ?? message);
+      message = String(data["message"] ?? data["error"] ?? data["detail"] ?? message);
+      billing = this.parseBilling(data);
     } catch {
     }
-    throw new AggregatorError(`Aggregator error: ${message}`, response.status);
+    throw new AggregatorError(`Aggregator error: ${message}`, response.status, void 0, billing);
   }
   /**
    * Build the request body for the aggregator.
@@ -2496,6 +2500,9 @@ var ChatResource = class _ChatResource {
     if (options.peerChannel) {
       body["peer_channel"] = options.peerChannel;
     }
+    if (options.retrievalOnly) {
+      body["retrieval_only"] = true;
+    }
     return body;
   }
   /**
@@ -2529,6 +2536,60 @@ var ChatResource = class _ChatResource {
       totalTokens: Number(data["total_tokens"] ?? 0)
     };
   }
+  /**
+   * 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) {
+    const recipientRaw = raw["recipient"];
+    const recipient = recipientRaw && typeof recipientRaw === "object" ? {
+      username: recipientRaw["username"],
+      email: recipientRaw["email"],
+      walletAddress: recipientRaw["wallet_address"]
+    } : void 0;
+    const transactionRaw = raw["transaction"];
+    const transaction = transactionRaw && typeof transactionRaw === "object" ? {
+      rail: String(transactionRaw["rail"] ?? ""),
+      id: String(transactionRaw["id"] ?? ""),
+      reference: transactionRaw["reference"]
+    } : void 0;
+    return {
+      source: raw["source"],
+      policyType: String(raw["policy_type"] ?? ""),
+      kind: String(raw["kind"] ?? ""),
+      status: String(raw["status"] ?? ""),
+      amount: raw["amount"] == null ? void 0 : Number(raw["amount"]),
+      currency: raw["currency"],
+      recipient,
+      transaction,
+      reasonCode: raw["reason_code"],
+      reason: raw["reason"],
+      details: raw["details"] ?? {}
+    };
+  }
+  /**
+   * 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.
+   */
+  parseBilling(data) {
+    const b = data["billing"];
+    if (!b || typeof b !== "object") {
+      return void 0;
+    }
+    const billing = b;
+    const entriesRaw = Array.isArray(billing["entries"]) ? billing["entries"] : [];
+    return {
+      totalCost: billing["total_cost"] == null ? null : Number(billing["total_cost"]),
+      currency: billing["currency"] ?? null,
+      entries: entriesRaw.map(
+        (e) => _ChatResource.parseBillingEntry(e)
+      )
+    };
+  }
   /**
    * Parse document sources from raw data.
    * The new format is a dict mapping document title to {slug, content}.
@@ -2596,15 +2657,82 @@ var ChatResource = class _ChatResource {
     const usageData = data["usage"];
     const usage = usageData ? this.parseUsage(usageData) : void 0;
     const profitShare = data["profit_share"];
+    const billing = this.parseBilling(data);
     return {
       response: String(data["response"] ?? ""),
       sources,
       retrievalInfo,
       metadata,
       usage,
-      profitShare
+      profitShare,
+      billing
     };
   }
+  /**
+   * 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.
+   */
+  static RETRIEVAL_ONLY_MODEL = {
+    url: "",
+    slug: "",
+    name: "retrieval-only"
+  };
+  /**
+   * 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
+   */
+  async retrieve(options) {
+    const chatOptions = {
+      prompt: options.prompt,
+      model: _ChatResource.RETRIEVAL_ONLY_MODEL,
+      dataSources: options.dataSources,
+      topK: options.topK,
+      similarityThreshold: options.similarityThreshold,
+      aggregatorUrl: options.aggregatorUrl,
+      guestMode: options.guestMode
+    };
+    const { requestBody, effectiveAggregatorUrl } = await this.prepareRequest(
+      chatOptions,
+      false,
+      true
+    );
+    const response = await fetch(`${effectiveAggregatorUrl}/chat`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(requestBody),
+      signal: options.signal
+    });
+    if (!response.ok) {
+      return this.handleAggregatorErrorResponse(response);
+    }
+    const data = await response.json();
+    const sources = this.parseDocumentSources(
+      data["sources"]
+    );
+    const documents = Object.entries(sources).map(([title, source]) => ({
+      title,
+      slug: source.slug,
+      content: source.content
+    }));
+    const retrievalInfo = this.parseRetrievalInfo(
+      data["retrieval_info"]
+    );
+    const metadata = this.parseMetadata(data["metadata"] ?? {});
+    const billing = this.parseBilling(data);
+    return { documents, retrievalInfo, metadata, billing };
+  }
   /**
    * Send a chat request and stream response events.
    *
@@ -2703,13 +2831,24 @@ var ChatResource = class _ChatResource {
         const usageData = data["usage"];
         const usage = usageData ? this.parseUsage(usageData) : void 0;
         const profitShare = data["profit_share"];
+        const billing = this.parseBilling(data);
         const response = data["response"];
-        return { type: "done", sources, retrievalInfo, metadata, usage, profitShare, response };
+        return {
+          type: "done",
+          sources,
+          retrievalInfo,
+          metadata,
+          usage,
+          profitShare,
+          billing,
+          response
+        };
       }
       case "error":
         return {
           type: "error",
-          message: String(data["message"] ?? "Unknown error")
+          message: String(data["message"] ?? "Unknown error"),
+          billing: this.parseBilling(data)
         };
       default:
         console.warn(`[SyftHub] Unknown SSE event type received from aggregator: ${eventType}`);
@@ -2750,6 +2889,34 @@ var ChatResource = class _ChatResource {
   }
 };
 
+// src/resources/search.ts
+var SearchResource = class {
+  /**
+   * @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) {
+    this.chat = chat;
+  }
+  /**
+   * 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');
+   */
+  async query(options) {
+    return this.chat.retrieve(options);
+  }
+};
+
 // src/resources/syftai.ts
 init_errors();
 var RetrievalError = class extends exports.SyftHubError {
@@ -2865,6 +3032,28 @@ var SyftAIResource = class {
     }
     return documents;
   }
+  /**
+   * 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.
+   */
+  parsePolicyMetadata(data) {
+    const pm = data["policy_metadata"];
+    if (!pm || typeof pm !== "object") {
+      return void 0;
+    }
+    const meta = pm;
+    const entriesRaw = Array.isArray(meta["entries"]) ? meta["entries"] : [];
+    return {
+      outcome: String(meta["outcome"] ?? ""),
+      entries: entriesRaw.map(
+        (e) => ChatResource.parseBillingEntry(e)
+      )
+    };
+  }
   /**
    * Query a data source endpoint directly.
    *
@@ -2874,7 +3063,9 @@ var SyftAIResource = class {
    * 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
    */
   async queryDataSource(options) {
@@ -2945,8 +3136,10 @@ var SyftAIResource = class {
       throw new RetrievalError(`Data source query failed: ${message}`, endpoint.slug);
     }
     const data = await response.json();
-    const documents = this.parseDocuments(data);
-    return documents;
+    return {
+      documents: this.parseDocuments(data),
+      policyMetadata: this.parsePolicyMetadata(data)
+    };
   }
   /**
    * Query a model endpoint directly.
@@ -3083,8 +3276,10 @@ var SyftHubClient = class {
   _myEndpoints;
   _hub;
   _accounting;
+  _aggregators;
   _agent;
   _chat;
+  _search;
   _syftai;
   _apiTokens;
   /**
@@ -3203,43 +3398,23 @@ var SyftHubClient = class {
    * const balance = await client.accounting.getBalance();
    */
   get accounting() {
-    if (this._accounting) {
-      return this._accounting;
-    }
-    throw new exports.AuthenticationError(
-      "Accounting not initialized. Call `await client.initAccounting()` after login."
-    );
-  }
-  /**
-   * 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();
-   */
-  async initAccounting() {
-    if (this._accounting) {
-      return this._accounting;
-    }
     if (!this.isAuthenticated) {
       throw new exports.AuthenticationError(
         "Must be logged in to use accounting. Call client.auth.login() first."
       );
     }
-    this._accounting = new AccountingResource(this.http);
+    if (!this._accounting) {
+      this._accounting = new AccountingResource(this.http);
+    }
     return this._accounting;
   }
+  /**
+   * @deprecated Accounting is now initialized automatically on first access.
+   * This method is kept for backward compatibility and is a no-op.
+   */
+  async initAccounting() {
+    return this.accounting;
+  }
   /**
    * Chat resource for RAG-augmented conversations via the Aggregator.
    *
@@ -3272,6 +3447,28 @@ var SyftHubClient = class {
     }
     return this._chat;
   }
+  /**
+   * 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() {
+    if (!this._search) {
+      this._search = new SearchResource(this.chat);
+    }
+    return this._search;
+  }
   /**
    * SyftAI-Space resource for direct endpoint queries (low-level API).
    *
@@ -3322,6 +3519,12 @@ var SyftHubClient = class {
    * // Revoke a token
    * await client.apiTokens.revoke(tokenId);
    */
+  get aggregators() {
+    if (!this._aggregators) {
+      this._aggregators = new AggregatorsResource(this.http);
+    }
+    return this._aggregators;
+  }
   get apiTokens() {
     if (!this._apiTokens) {
       this._apiTokens = new APITokensResource(this.http);
@@ -3417,6 +3620,7 @@ exports.EndpointType = EndpointType;
 exports.GenerationError = GenerationError;
 exports.PageIterator = PageIterator;
 exports.RetrievalError = RetrievalError;
+exports.SearchResource = SearchResource;
 exports.SyftAIResource = SyftAIResource;
 exports.SyftHubClient = SyftHubClient;
 exports.UserRole = UserRole;