@syfthub/sdk 0.2.0 → 0.2.1

package/dist/index.d.cts

@@ -909,6 +909,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.
@@ -2785,13 +2801,50 @@ 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;
     /**
      * 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
      * @throws {RetrievalError} If the query fails

package/dist/index.d.ts

@@ -909,6 +909,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.
@@ -2785,13 +2801,50 @@ 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;
     /**
      * 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
      * @throws {RetrievalError} If the query fails

package/dist/index.js

@@ -2767,28 +2767,125 @@ var GenerationError = class extends SyftHubError {
   }
 };
 var SyftAIResource = class {
-  // No dependencies - uses direct fetch to SyftAI-Space endpoints
+  /**
+   * @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) {
+    this.http = http;
+  }
+  /**
+   * 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.
+   */
+  async mintSatelliteToken(audience) {
+    if (this.http.hasTokens()) {
+      try {
+        const res = await this.http.get("/api/v1/token", {
+          aud: audience
+        });
+        if (res.targetToken) return res.targetToken;
+      } catch {
+      }
+    }
+    try {
+      const res = await this.http.get(
+        "/api/v1/token/guest",
+        { aud: audience },
+        { includeAuth: false }
+      );
+      return res.targetToken;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * 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.
+   */
+  async payMpp(wwwAuthenticate, slug) {
+    if (!wwwAuthenticate) return void 0;
+    const res = await this.http.post("/api/v1/wallet/pay", {
+      wwwAuthenticate,
+      endpointSlug: slug
+    });
+    return res.xPayment;
+  }
   /**
    * Build headers for SyftAI-Space request.
    */
-  buildHeaders(tenantName) {
+  buildHeaders(tenantName, authorizationToken) {
     const headers = {
       "Content-Type": "application/json"
     };
     if (tenantName) {
       headers["X-Tenant-Name"] = tenantName;
     }
+    if (authorizationToken) {
+      headers["Authorization"] = `Bearer ${authorizationToken}`;
+    }
     return headers;
   }
+  /**
+   * 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.
+   */
+  parseDocuments(data) {
+    const references = data["references"];
+    let rawDocs;
+    let scoreKey = "score";
+    if (references && typeof references === "object") {
+      rawDocs = references["documents"];
+      scoreKey = "similarity_score";
+    } else {
+      rawDocs = data["documents"];
+    }
+    const documents = [];
+    if (Array.isArray(rawDocs)) {
+      for (const doc of rawDocs) {
+        documents.push({
+          content: String(doc["content"] ?? ""),
+          score: Number(doc[scoreKey] ?? doc["score"] ?? 0),
+          metadata: doc["metadata"] ?? {}
+        });
+      }
+    }
+    return documents;
+  }
   /**
    * 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
    * @throws {RetrievalError} If the query fails
    */
   async queryDataSource(options) {
-    const { endpoint, query, userEmail, topK = 5, similarityThreshold = 0.5 } = options;
+    const {
+      endpoint,
+      query,
+      userEmail,
+      topK = 5,
+      similarityThreshold = 0.5,
+      authorizationToken,
+      ownerUsername,
+      pay = false
+    } = options;
     const url = `${endpoint.url.replace(/\/$/, "")}/api/v1/endpoints/${endpoint.slug}/query`;
     const requestBody = {
       user_email: userEmail,
@@ -2797,19 +2894,44 @@ var SyftAIResource = class {
       limit: topK,
       similarity_threshold: similarityThreshold
     };
-    let response;
-    try {
-      response = await fetch(url, {
-        method: "POST",
-        headers: this.buildHeaders(endpoint.tenantName),
-        body: JSON.stringify(requestBody)
-      });
-    } catch (error) {
-      throw new RetrievalError(
-        `Failed to connect to data source '${endpoint.slug}': ${error instanceof Error ? error.message : String(error)}`,
-        endpoint.slug,
-        error
-      );
+    let token = authorizationToken;
+    if (!token) {
+      const audience = ownerUsername ?? endpoint.ownerUsername;
+      if (audience) {
+        token = await this.mintSatelliteToken(audience);
+      }
+    }
+    const headers = this.buildHeaders(endpoint.tenantName, token);
+    const postQuery = async (extraHeaders) => {
+      try {
+        return await fetch(url, {
+          method: "POST",
+          headers: { ...headers, ...extraHeaders },
+          body: JSON.stringify(requestBody)
+        });
+      } catch (error) {
+        throw new RetrievalError(
+          `Failed to connect to data source '${endpoint.slug}': ${error instanceof Error ? error.message : String(error)}`,
+          endpoint.slug,
+          error
+        );
+      }
+    };
+    let response = await postQuery();
+    if (response.status === 402 && pay) {
+      let xPayment;
+      try {
+        xPayment = await this.payMpp(response.headers.get("www-authenticate") ?? "", endpoint.slug);
+      } catch (error) {
+        throw new RetrievalError(
+          `Payment failed for data source '${endpoint.slug}': ${error instanceof Error ? error.message : String(error)}`,
+          endpoint.slug,
+          error
+        );
+      }
+      if (xPayment) {
+        response = await postQuery({ "X-Payment": xPayment });
+      }
     }
     if (!response.ok) {
       let message = `HTTP ${response.status}`;
@@ -2821,17 +2943,7 @@ var SyftAIResource = class {
       throw new RetrievalError(`Data source query failed: ${message}`, endpoint.slug);
     }
     const data = await response.json();
-    const documents = [];
-    const docsData = data["documents"];
-    if (Array.isArray(docsData)) {
-      for (const doc of docsData) {
-        documents.push({
-          content: String(doc["content"] ?? ""),
-          score: Number(doc["score"] ?? 0),
-          metadata: doc["metadata"] ?? {}
-        });
-      }
-    }
+    const documents = this.parseDocuments(data);
     return documents;
   }
   /**
@@ -3184,7 +3296,7 @@ var SyftHubClient = class {
    */
   get syftai() {
     if (!this._syftai) {
-      this._syftai = new SyftAIResource();
+      this._syftai = new SyftAIResource(this.http);
     }
     return this._syftai;
   }