@dexterai/x402 3.0.0 → 3.1.0

package/dist/client/index.d.cts

@@ -4,6 +4,7 @@ export { b as AccessPassInfo, a as AccessPassTier, D as DEXTER_FACILITATOR_URL,
 import { Keypair } from '@solana/web3.js';
 import { S as SolanaWallet, E as EvmWallet } from '../types-C_aQh02s.cjs';
 export { B as BASE_MAINNET, C as ChainAdapter, b as SOLANA_MAINNET, W as WalletSet, a as createEvmAdapter, c as createSolanaAdapter } from '../types-C_aQh02s.cjs';
+export { FormattedResource as CapabilityAPI, CapabilitySearchOptions, CapabilitySearchResult, NoMatchReason, capabilitySearch } from '@dexterai/x402-core';
 export { SponsoredAccessSettlementInfo, SponsoredRecommendation } from '@dexterai/x402-ads-types';
 
 /**
@@ -237,228 +238,6 @@ declare function createEvmKeypairWallet(privateKey: string): Promise<EvmWallet>;
  */
 declare function isEvmKeypairWallet(wallet: unknown): wallet is EvmWallet;
 
-/**
- * API Discovery — Semantic Capability Search
- *
- * Search the Dexter x402 marketplace for paid APIs using semantic capability
- * search. Queries are embedded with a vector model, filtered by a similarity
- * floor, split into strong and related tiers, and the top strong results are
- * reordered by an LLM cross-encoder. Synonym expansion and alternate phrasing
- * handling happen automatically inside the search backend — pass a natural-
- * language query and let the ranker do the work.
- *
- * @example
- * ```typescript
- * import { capabilitySearch } from '@dexterai/x402/client';
- *
- * const result = await capabilitySearch({ query: 'get ETH spot price' });
- *
- * // Strong matches: high-confidence capability hits
- * for (const api of result.strongResults) {
- *   console.log(`${api.name} (${api.tier}, similarity ${api.similarity}): ${api.why}`);
- * }
- *
- * // Related matches: adjacent services that cleared the similarity floor
- * // but not the strong threshold. Useful as a fallback when strongResults
- * // is empty or sparse.
- * for (const api of result.relatedResults) {
- *   console.log(`${api.name} (related): ${api.description}`);
- * }
- *
- * // Then call one with wrapFetch:
- * const response = await x402Fetch(result.strongResults[0].url);
- * ```
- *
- * @breaking 3.0.0
- * This module was rewritten to target the capability search endpoint at
- * `/api/x402gle/capability` instead of the legacy substring ranker at
- * `/api/facilitator/marketplace/resources`. The old `searchAPIs()` function
- * and `DiscoveredAPI` type have been removed — replaced by `capabilitySearch()`
- * and `CapabilityAPI`. The response is now tiered (strongResults/relatedResults)
- * and each result carries `tier`, `similarity`, and `why` explainers. Filter
- * parameters like `category`, `network`, `maxPrice`, `verifiedOnly`, and `sort`
- * are gone — the ranker handles these semantically rather than as hard filters.
- */
-/**
- * Options for semantic capability search.
- *
- * The new pipeline does NOT accept the old hard-filter params (`category`,
- * `network`, `maxPrice`, `verifiedOnly`, `sort`). Those were removed in 3.0.0
- * because they were the source of silent false-empties: e.g. a query for
- * "ETH price" on `network: 'ethereum'` would return zero results because
- * every ETH-price resource accepts payment on Base (Ethereum gas is too
- * expensive). Search ranks by capability relevance; payment rail is a
- * checkout-time concern the caller handles separately.
- */
-interface CapabilitySearchOptions {
-    /** Natural-language description of the capability you want. Required. */
-    query: string;
-    /** Max results across strong + related tiers combined (1-50, default 20) */
-    limit?: number;
-    /** Include unverified resources (default false) */
-    unverified?: boolean;
-    /** Include testnet-only resources (default false) */
-    testnets?: boolean;
-    /**
-     * Cross-encoder LLM rerank of the top strong results. Default true.
-     * Adds ~1s of latency in exchange for meaningfully better top-of-list
-     * ordering on ambiguous queries. Set to false for deterministic order
-     * or lowest-latency path.
-     */
-    rerank?: boolean;
-    /**
-     * Override the capability search endpoint. Defaults to the Dexter-hosted
-     * endpoint. Useful for testing against a local dexter-api instance.
-     */
-    endpoint?: string;
-}
-/**
- * A single result from capability search.
- *
- * Fields are flat-ish and designed to round-trip cleanly through LLM tool
- * outputs and UI renderers. `tier`, `similarity`, and `why` are the three
- * new fields that the ranker produces: use them to distinguish high-confidence
- * matches from related suggestions.
- */
-interface CapabilityAPI {
-    /** Internal resource UUID in the Dexter catalog */
-    resourceId: string;
-    /** Display name (falls back to the URL if the resource is unnamed) */
-    name: string;
-    /** Full resource URL — pass directly to wrapFetch or createX402Client.fetch */
-    url: string;
-    /** HTTP method the endpoint expects */
-    method: string;
-    /**
-     * Formatted price label ("$0.05", "$0.0011", "free", or "price on request"
-     * when the resource has no advertised price).
-     */
-    price: string;
-    /** Raw price in USDC as a number (null when the resource has no advertised price) */
-    priceUsdc: number | null;
-    /** Payment network the price is quoted on (CAIP-2 or canonical name) */
-    network: string | null;
-    /** Human-readable description */
-    description: string;
-    /** Category assigned by the catalog */
-    category: string;
-    /** Quality score 0-100 (null if unscored) */
-    qualityScore: number | null;
-    /** Whether the endpoint passed AI verification (alias for verificationStatus === 'pass') */
-    verified: boolean;
-    /** Full verification status: 'pass' | 'fail' | 'inconclusive' | 'skipped' | 'unverified' */
-    verificationStatus: string;
-    /** Total number of settlements (calls) observed against this resource */
-    totalCalls: number;
-    /** Total settled volume in USDC */
-    totalVolumeUsdc: number;
-    /** Icon URL (favicon or seller logo) */
-    iconUrl: string | null;
-    /** Host label derived from the URL */
-    host: string | null;
-    /** Gaming/wash-trading flags — non-empty array means the resource is suspicious */
-    gamingFlags: string[];
-    /** True when any gaming flag is set */
-    gamingSuspicious: boolean;
-    /** Which tier this result fell into — 'strong' (high confidence) or 'related' (adjacent) */
-    tier: 'strong' | 'related';
-    /** Raw cosine similarity 0-1 between the query embedding and the resource embedding */
-    similarity: number;
-    /**
-     * One-sentence explanation of why this result ranked where it did. Built
-     * from the modular ranking factors (semantic similarity, trust, activity,
-     * gaming penalty).
-     */
-    why: string;
-    /** Final combined ranking score in [0, 1] */
-    score: number;
-}
-/**
- * Why a response has no strong matches.
- * - 'below_similarity_threshold': no candidates cleared the similarity floor at all
- * - 'below_strong_threshold': candidates cleared the floor but none reached strong
- * - null: strongResults is non-empty
- */
-type NoMatchReason = 'below_similarity_threshold' | 'below_strong_threshold' | null;
-/**
- * Full response from capability search. Tiered shape with telemetry about
- * the ranking pipeline.
- */
-interface CapabilitySearchResult {
-    /** The original query string the caller passed */
-    query: string;
-    /**
-     * Strong matches — high-confidence capability hits (similarity >= strong
-     * threshold). These are the primary results the caller should surface.
-     */
-    strongResults: CapabilityAPI[];
-    /**
-     * Related matches — candidates that cleared the similarity floor but did
-     * not reach the strong threshold. Useful as a secondary section when
-     * strongResults is empty or sparse.
-     */
-    relatedResults: CapabilityAPI[];
-    /** Count of strong results returned */
-    strongCount: number;
-    /** Count of related results returned */
-    relatedCount: number;
-    /** Highest cosine similarity observed across all candidates (null when no candidates) */
-    topSimilarity: number | null;
-    /** Reason the response has no strong matches (null when strong matches exist) */
-    noMatchReason: NoMatchReason;
-    /**
-     * Cross-encoder rerank telemetry. `applied` is true when the LLM actually
-     * reordered the top strong results; `reason` explains any skip.
-     */
-    rerank: {
-        enabled: boolean;
-        applied: boolean;
-        reason?: string;
-    };
-    /**
-     * The parsed intent the backend extracted. `capabilityText` is the bare
-     * capability; `expandedCapabilityText` is the synonym-expanded version that
-     * was actually embedded for the vector search.
-     */
-    intent: {
-        capabilityText: string;
-        expandedCapabilityText?: string;
-    };
-    /** Total wall-clock duration of the capability search request in milliseconds */
-    durationMs: number;
-}
-/**
- * Search the Dexter x402 marketplace using semantic capability search.
- *
- * Returns tiered results (strongResults + relatedResults) plus ranking
- * telemetry. Handles synonym expansion and cross-encoder LLM rerank
- * internally — pass the user's natural-language intent directly.
- *
- * @example Find an ETH price feed
- * ```typescript
- * const result = await capabilitySearch({ query: 'get current ETH spot price' });
- * if (result.strongCount > 0) {
- *   const best = result.strongResults[0];
- *   console.log(`${best.name}: ${best.price} — ${best.why}`);
- * } else if (result.relatedCount > 0) {
- *   console.log(`No exact match. Closest related: ${result.relatedResults[0].name}`);
- * } else {
- *   console.log(`No match. Reason: ${result.noMatchReason}`);
- * }
- * ```
- *
- * @example Skip the LLM rerank for lowest latency
- * ```typescript
- * const result = await capabilitySearch({ query: 'token price', rerank: false });
- * ```
- *
- * @example Include unverified resources (usually omitted)
- * ```typescript
- * const result = await capabilitySearch({ query: 'image generation', unverified: true });
- * ```
- */
-declare function capabilitySearch(options: CapabilitySearchOptions): Promise<CapabilitySearchResult>;
-
 /**
  * Budget Account — Autonomous Agent Spending Controls
  *
@@ -544,4 +323,4 @@ interface BudgetAccount {
  */
 declare function createBudgetAccount(config: BudgetAccountConfig): BudgetAccount;
 
-export { AccessPassClientConfig, type BudgetAccount, type BudgetAccountConfig, type BudgetConfig, type CapabilityAPI, type CapabilitySearchOptions, type CapabilitySearchResult, KEYPAIR_SYMBOL, type KeypairWallet, type NoMatchReason, type PaymentRecord, type WrapFetchOptions, capabilitySearch, createBudgetAccount, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, wrapFetch };
+export { AccessPassClientConfig, type BudgetAccount, type BudgetAccountConfig, type BudgetConfig, KEYPAIR_SYMBOL, type KeypairWallet, type PaymentRecord, type WrapFetchOptions, createBudgetAccount, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, wrapFetch };

package/dist/client/index.d.ts

@@ -4,6 +4,7 @@ export { b as AccessPassInfo, a as AccessPassTier, D as DEXTER_FACILITATOR_URL,
 import { Keypair } from '@solana/web3.js';
 import { S as SolanaWallet, E as EvmWallet } from '../types-DBS0XOsH.js';
 export { B as BASE_MAINNET, C as ChainAdapter, b as SOLANA_MAINNET, W as WalletSet, a as createEvmAdapter, c as createSolanaAdapter } from '../types-DBS0XOsH.js';
+export { FormattedResource as CapabilityAPI, CapabilitySearchOptions, CapabilitySearchResult, NoMatchReason, capabilitySearch } from '@dexterai/x402-core';
 export { SponsoredAccessSettlementInfo, SponsoredRecommendation } from '@dexterai/x402-ads-types';
 
 /**
@@ -237,228 +238,6 @@ declare function createEvmKeypairWallet(privateKey: string): Promise<EvmWallet>;
  */
 declare function isEvmKeypairWallet(wallet: unknown): wallet is EvmWallet;
 
-/**
- * API Discovery — Semantic Capability Search
- *
- * Search the Dexter x402 marketplace for paid APIs using semantic capability
- * search. Queries are embedded with a vector model, filtered by a similarity
- * floor, split into strong and related tiers, and the top strong results are
- * reordered by an LLM cross-encoder. Synonym expansion and alternate phrasing
- * handling happen automatically inside the search backend — pass a natural-
- * language query and let the ranker do the work.
- *
- * @example
- * ```typescript
- * import { capabilitySearch } from '@dexterai/x402/client';
- *
- * const result = await capabilitySearch({ query: 'get ETH spot price' });
- *
- * // Strong matches: high-confidence capability hits
- * for (const api of result.strongResults) {
- *   console.log(`${api.name} (${api.tier}, similarity ${api.similarity}): ${api.why}`);
- * }
- *
- * // Related matches: adjacent services that cleared the similarity floor
- * // but not the strong threshold. Useful as a fallback when strongResults
- * // is empty or sparse.
- * for (const api of result.relatedResults) {
- *   console.log(`${api.name} (related): ${api.description}`);
- * }
- *
- * // Then call one with wrapFetch:
- * const response = await x402Fetch(result.strongResults[0].url);
- * ```
- *
- * @breaking 3.0.0
- * This module was rewritten to target the capability search endpoint at
- * `/api/x402gle/capability` instead of the legacy substring ranker at
- * `/api/facilitator/marketplace/resources`. The old `searchAPIs()` function
- * and `DiscoveredAPI` type have been removed — replaced by `capabilitySearch()`
- * and `CapabilityAPI`. The response is now tiered (strongResults/relatedResults)
- * and each result carries `tier`, `similarity`, and `why` explainers. Filter
- * parameters like `category`, `network`, `maxPrice`, `verifiedOnly`, and `sort`
- * are gone — the ranker handles these semantically rather than as hard filters.
- */
-/**
- * Options for semantic capability search.
- *
- * The new pipeline does NOT accept the old hard-filter params (`category`,
- * `network`, `maxPrice`, `verifiedOnly`, `sort`). Those were removed in 3.0.0
- * because they were the source of silent false-empties: e.g. a query for
- * "ETH price" on `network: 'ethereum'` would return zero results because
- * every ETH-price resource accepts payment on Base (Ethereum gas is too
- * expensive). Search ranks by capability relevance; payment rail is a
- * checkout-time concern the caller handles separately.
- */
-interface CapabilitySearchOptions {
-    /** Natural-language description of the capability you want. Required. */
-    query: string;
-    /** Max results across strong + related tiers combined (1-50, default 20) */
-    limit?: number;
-    /** Include unverified resources (default false) */
-    unverified?: boolean;
-    /** Include testnet-only resources (default false) */
-    testnets?: boolean;
-    /**
-     * Cross-encoder LLM rerank of the top strong results. Default true.
-     * Adds ~1s of latency in exchange for meaningfully better top-of-list
-     * ordering on ambiguous queries. Set to false for deterministic order
-     * or lowest-latency path.
-     */
-    rerank?: boolean;
-    /**
-     * Override the capability search endpoint. Defaults to the Dexter-hosted
-     * endpoint. Useful for testing against a local dexter-api instance.
-     */
-    endpoint?: string;
-}
-/**
- * A single result from capability search.
- *
- * Fields are flat-ish and designed to round-trip cleanly through LLM tool
- * outputs and UI renderers. `tier`, `similarity`, and `why` are the three
- * new fields that the ranker produces: use them to distinguish high-confidence
- * matches from related suggestions.
- */
-interface CapabilityAPI {
-    /** Internal resource UUID in the Dexter catalog */
-    resourceId: string;
-    /** Display name (falls back to the URL if the resource is unnamed) */
-    name: string;
-    /** Full resource URL — pass directly to wrapFetch or createX402Client.fetch */
-    url: string;
-    /** HTTP method the endpoint expects */
-    method: string;
-    /**
-     * Formatted price label ("$0.05", "$0.0011", "free", or "price on request"
-     * when the resource has no advertised price).
-     */
-    price: string;
-    /** Raw price in USDC as a number (null when the resource has no advertised price) */
-    priceUsdc: number | null;
-    /** Payment network the price is quoted on (CAIP-2 or canonical name) */
-    network: string | null;
-    /** Human-readable description */
-    description: string;
-    /** Category assigned by the catalog */
-    category: string;
-    /** Quality score 0-100 (null if unscored) */
-    qualityScore: number | null;
-    /** Whether the endpoint passed AI verification (alias for verificationStatus === 'pass') */
-    verified: boolean;
-    /** Full verification status: 'pass' | 'fail' | 'inconclusive' | 'skipped' | 'unverified' */
-    verificationStatus: string;
-    /** Total number of settlements (calls) observed against this resource */
-    totalCalls: number;
-    /** Total settled volume in USDC */
-    totalVolumeUsdc: number;
-    /** Icon URL (favicon or seller logo) */
-    iconUrl: string | null;
-    /** Host label derived from the URL */
-    host: string | null;
-    /** Gaming/wash-trading flags — non-empty array means the resource is suspicious */
-    gamingFlags: string[];
-    /** True when any gaming flag is set */
-    gamingSuspicious: boolean;
-    /** Which tier this result fell into — 'strong' (high confidence) or 'related' (adjacent) */
-    tier: 'strong' | 'related';
-    /** Raw cosine similarity 0-1 between the query embedding and the resource embedding */
-    similarity: number;
-    /**
-     * One-sentence explanation of why this result ranked where it did. Built
-     * from the modular ranking factors (semantic similarity, trust, activity,
-     * gaming penalty).
-     */
-    why: string;
-    /** Final combined ranking score in [0, 1] */
-    score: number;
-}
-/**
- * Why a response has no strong matches.
- * - 'below_similarity_threshold': no candidates cleared the similarity floor at all
- * - 'below_strong_threshold': candidates cleared the floor but none reached strong
- * - null: strongResults is non-empty
- */
-type NoMatchReason = 'below_similarity_threshold' | 'below_strong_threshold' | null;
-/**
- * Full response from capability search. Tiered shape with telemetry about
- * the ranking pipeline.
- */
-interface CapabilitySearchResult {
-    /** The original query string the caller passed */
-    query: string;
-    /**
-     * Strong matches — high-confidence capability hits (similarity >= strong
-     * threshold). These are the primary results the caller should surface.
-     */
-    strongResults: CapabilityAPI[];
-    /**
-     * Related matches — candidates that cleared the similarity floor but did
-     * not reach the strong threshold. Useful as a secondary section when
-     * strongResults is empty or sparse.
-     */
-    relatedResults: CapabilityAPI[];
-    /** Count of strong results returned */
-    strongCount: number;
-    /** Count of related results returned */
-    relatedCount: number;
-    /** Highest cosine similarity observed across all candidates (null when no candidates) */
-    topSimilarity: number | null;
-    /** Reason the response has no strong matches (null when strong matches exist) */
-    noMatchReason: NoMatchReason;
-    /**
-     * Cross-encoder rerank telemetry. `applied` is true when the LLM actually
-     * reordered the top strong results; `reason` explains any skip.
-     */
-    rerank: {
-        enabled: boolean;
-        applied: boolean;
-        reason?: string;
-    };
-    /**
-     * The parsed intent the backend extracted. `capabilityText` is the bare
-     * capability; `expandedCapabilityText` is the synonym-expanded version that
-     * was actually embedded for the vector search.
-     */
-    intent: {
-        capabilityText: string;
-        expandedCapabilityText?: string;
-    };
-    /** Total wall-clock duration of the capability search request in milliseconds */
-    durationMs: number;
-}
-/**
- * Search the Dexter x402 marketplace using semantic capability search.
- *
- * Returns tiered results (strongResults + relatedResults) plus ranking
- * telemetry. Handles synonym expansion and cross-encoder LLM rerank
- * internally — pass the user's natural-language intent directly.
- *
- * @example Find an ETH price feed
- * ```typescript
- * const result = await capabilitySearch({ query: 'get current ETH spot price' });
- * if (result.strongCount > 0) {
- *   const best = result.strongResults[0];
- *   console.log(`${best.name}: ${best.price} — ${best.why}`);
- * } else if (result.relatedCount > 0) {
- *   console.log(`No exact match. Closest related: ${result.relatedResults[0].name}`);
- * } else {
- *   console.log(`No match. Reason: ${result.noMatchReason}`);
- * }
- * ```
- *
- * @example Skip the LLM rerank for lowest latency
- * ```typescript
- * const result = await capabilitySearch({ query: 'token price', rerank: false });
- * ```
- *
- * @example Include unverified resources (usually omitted)
- * ```typescript
- * const result = await capabilitySearch({ query: 'image generation', unverified: true });
- * ```
- */
-declare function capabilitySearch(options: CapabilitySearchOptions): Promise<CapabilitySearchResult>;
-
 /**
  * Budget Account — Autonomous Agent Spending Controls
  *
@@ -544,4 +323,4 @@ interface BudgetAccount {
  */
 declare function createBudgetAccount(config: BudgetAccountConfig): BudgetAccount;
 
-export { AccessPassClientConfig, type BudgetAccount, type BudgetAccountConfig, type BudgetConfig, type CapabilityAPI, type CapabilitySearchOptions, type CapabilitySearchResult, KEYPAIR_SYMBOL, type KeypairWallet, type NoMatchReason, type PaymentRecord, type WrapFetchOptions, capabilitySearch, createBudgetAccount, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, wrapFetch };
+export { AccessPassClientConfig, type BudgetAccount, type BudgetAccountConfig, type BudgetConfig, KEYPAIR_SYMBOL, type KeypairWallet, type PaymentRecord, type WrapFetchOptions, createBudgetAccount, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, wrapFetch };