@piprail/sdk 2.0.2 → 2.1.0

package/dist/index.js

@@ -2019,14 +2019,114 @@ function normalizeNetwork(network) {
 async function searchOpenIndexes(opts = {}) {
   const sources = opts.sources ?? ["bazaar", "402index"];
   const limit = opts.limit ?? 20;
+  const filters = {
+    ...optionalRaw("category", opts.category),
+    ...optionalRaw("asset", opts.asset),
+    ...optionalRaw("maxPrice", opts.maxPrice),
+    ...optionalRaw("verified", opts.verified),
+    ...optionalRaw("paymentValid", opts.paymentValid),
+    ...optionalRaw("sort", opts.sort),
+    ...optionalRaw("order", opts.order)
+  };
   const results = await Promise.all(
     sources.map((source) => {
       if (source === "bazaar") return safeSearch(() => searchBazaar(opts.query, limit, opts.signal));
-      if (source === "402index") return safeSearch(() => search402Index(opts.query, limit, opts.signal));
+      if (source === "402index") return safeSearch(() => search402Index(opts.query, limit, filters, opts.signal));
       return Promise.resolve([]);
     })
   );
-  return dedupeByResource(results.flat());
+  const merged = applyClientFilters(dedupeByResource(results.flat()), opts);
+  const wantRelevance = opts.query !== void 0 && (opts.sort ?? "relevance") === "relevance";
+  if (wantRelevance) return rankResources(merged, opts.query);
+  if (opts.sort && opts.sort !== "relevance") return sortResources(merged, opts.sort, opts.order ?? "desc");
+  return merged;
+}
+function optionalRaw(field, value) {
+  return value !== void 0 ? { [field]: value } : {};
+}
+function applyClientFilters(items, opts) {
+  let out = items;
+  if (opts.category) {
+    const want = opts.category.toLowerCase();
+    out = out.filter((r) => r.category !== void 0 && r.category.toLowerCase().startsWith(want));
+  }
+  if (opts.maxPrice !== void 0) {
+    const max = opts.maxPrice;
+    out = out.filter((r) => r.priceUsd === void 0 || r.priceUsd <= max);
+  }
+  if (opts.asset) {
+    const want = opts.asset.toLowerCase();
+    out = out.filter((r) => {
+      const known = r.rails.map((x) => x.symbol ?? x.asset).filter((a) => !!a);
+      return known.length === 0 || known.some((a) => a.toLowerCase() === want);
+    });
+  }
+  if (opts.minReliability !== void 0) {
+    const min = opts.minReliability;
+    out = out.filter((r) => r.reliabilityScore === void 0 || r.reliabilityScore >= min);
+  }
+  return out;
+}
+function tokenize(s) {
+  return (s ?? "").toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+var FIELD_WEIGHTS = { name: 6, category: 4, tags: 4, path: 3, description: 2 };
+function fieldTokens(r) {
+  let pathText = r.resource;
+  try {
+    const u = new URL(r.resource);
+    pathText = `${u.hostname} ${u.pathname}`;
+  } catch {
+  }
+  return [
+    [tokenize(r.name), FIELD_WEIGHTS.name],
+    [tokenize(r.category), FIELD_WEIGHTS.category],
+    [tokenize((r.tags ?? []).join(" ")), FIELD_WEIGHTS.tags],
+    [tokenize(pathText), FIELD_WEIGHTS.path],
+    [tokenize(r.description), FIELD_WEIGHTS.description]
+  ];
+}
+function scoreResource(r, queryTokens) {
+  if (queryTokens.length === 0) return 0;
+  const fields = fieldTokens(r);
+  let score = 0;
+  let matched = 0;
+  for (const qt of queryTokens) {
+    let hit = false;
+    for (const [toks, w] of fields) {
+      if (toks.includes(qt)) {
+        score += w;
+        hit = true;
+      } else if (qt.length >= 4 && toks.some((t) => t.startsWith(qt) || t.length >= 4 && qt.startsWith(t))) {
+        score += w * 0.4;
+        hit = true;
+      }
+    }
+    if (hit) matched++;
+  }
+  if (matched === 0) return 0;
+  if (matched === queryTokens.length) score += 8;
+  if (r.reliabilityScore !== void 0) score += r.reliabilityScore / 1e3;
+  return score;
+}
+function rankResources(items, query) {
+  const qTokens = tokenize(query);
+  if (qTokens.length === 0) return items;
+  return items.map((r, i) => ({ r, i, s: scoreResource(r, qTokens) })).filter((x) => x.s > 0).sort((a, b) => b.s - a.s || a.i - b.i).map((x) => ({ ...x.r, score: x.s }));
+}
+function sortResources(items, sort, order) {
+  const dir = order === "asc" ? 1 : -1;
+  const key = (r) => sort === "reliability" || sort === "uptime" ? r.reliabilityScore : sort === "price" ? r.priceUsd : sort === "name" ? (r.name ?? r.resource).toLowerCase() : void 0;
+  return items.map((r, i) => ({ r, i })).sort((a, b) => {
+    const ka = key(a.r);
+    const kb = key(b.r);
+    if (ka === void 0 && kb === void 0) return a.i - b.i;
+    if (ka === void 0) return 1;
+    if (kb === void 0) return -1;
+    if (ka < kb) return -1 * dir;
+    if (ka > kb) return 1 * dir;
+    return a.i - b.i;
+  }).map((x) => x.r);
 }
 async function safeSearch(run) {
   try {
@@ -2072,9 +2172,24 @@ function mapBazaarItem(raw) {
     ...optionalString("category", pickString(meta, "category"))
   };
 }
-async function search402Index(query, limit, signal) {
+async function search402Index(query, limit, filters, signal) {
+  const tokens = tokenize(query);
+  const queries = query && tokens.length > 1 ? [.../* @__PURE__ */ new Set([query, ...tokens])].slice(0, 5) : [query];
+  const pages = await Promise.all(queries.map((q) => safeSearch(() => fetch402Page(q, limit, filters, signal))));
+  return dedupeByResource(pages.flat());
+}
+async function fetch402Page(query, limit, filters, signal) {
   const qs = new URLSearchParams({ limit: String(limit) });
   if (query) qs.set("q", query);
+  if (filters.category) qs.set("category", filters.category);
+  if (filters.asset) qs.set("payment_asset", filters.asset);
+  if (filters.maxPrice !== void 0) qs.set("max_price_usd", String(filters.maxPrice));
+  if (filters.verified) qs.set("verified", "true");
+  if (filters.paymentValid) qs.set("payment_valid", "true");
+  if (filters.sort && filters.sort !== "relevance") {
+    qs.set("sort", filters.sort);
+    qs.set("order", filters.order ?? "desc");
+  }
   const res = await fetch(`${INDEX402_SEARCH}?${qs.toString()}`, {
     headers: clientHeaders({ accept: "application/json" }),
     ...signal ? { signal } : {}
@@ -2093,16 +2208,26 @@ function map402IndexItem(raw) {
   if (protocol !== "x402") return null;
   const rails = Array.isArray(o.accepts) ? mapRails(o.accepts) : railFrom402IndexFields(o);
   const priceUsd = pickNumber(o, "price_usd", "priceUsd", "price");
+  const reliabilityScore = pickNumber(o, "reliability_score", "reliabilityScore");
+  const tags = pickStringArray(o, "tags", "keywords");
   return {
     resource,
     source: "402index",
     rails,
     ...priceUsd !== void 0 ? { priceUsd } : {},
+    ...reliabilityScore !== void 0 ? { reliabilityScore } : {},
+    ...tags ? { tags } : {},
     ...optionalString("name", pickString(o, "name", "title")),
     ...optionalString("description", pickString(o, "description")),
-    ...optionalString("category", pickString(o, "category", "tag"))
+    ...optionalString("category", pickString(o, "category", "tag")),
+    ...optionalString("health", pickString(o, "health_status", "health")),
+    // 402 Index reports domain_verified as 0/1; surface a boolean only when the field is present.
+    ...o.domain_verified !== void 0 || o.verified !== void 0 ? { verified: isTruthyFlag(o.domain_verified) || isTruthyFlag(o.verified) } : {}
   };
 }
+function isTruthyFlag(v) {
+  return v === 1 || v === true || v === "1" || v === "true";
+}
 function railFrom402IndexFields(o) {
   const network = pickString(o, "payment_network", "network");
   const asset = pickString(o, "payment_asset", "asset", "token");
@@ -2119,7 +2244,8 @@ function railFrom402IndexFields(o) {
 async function register402Index(input) {
   try {
     const attributionOn = input.attribution !== false;
-    const description = attributionOn ? appendAttribution(input.description) : input.description;
+    const withTags = appendKeywords(input.description, input.tags);
+    const description = attributionOn ? appendAttribution(withTags) : withTags;
     const payload = {
       url: input.url,
       name: input.name ?? hostOf(input.url),
@@ -2129,6 +2255,11 @@ async function register402Index(input) {
       ...input.asset ? { payment_asset: input.asset } : {},
       ...input.network ? { payment_network: input.network } : {},
       ...input.method ? { http_method: input.method.toUpperCase() } : {},
+      ...input.category ? { category: input.category } : {},
+      ...input.tags && input.tags.length > 0 ? { tags: input.tags } : {},
+      ...input.provider ? { provider: input.provider } : {},
+      ...input.contactEmail ? { contact_email: input.contactEmail } : {},
+      ...input.probeBody !== void 0 ? { probe_body: input.probeBody } : {},
       ...attributionOn ? { via: "@piprail/sdk" } : {}
     };
     const res = await fetch(INDEX402_REGISTER, {
@@ -2335,8 +2466,24 @@ function mapRails(accepts) {
   return out;
 }
 function matchesQuery(r, query) {
-  const q = query.toLowerCase();
-  return r.resource.toLowerCase().includes(q) || (r.name?.toLowerCase().includes(q) ?? false) || (r.description?.toLowerCase().includes(q) ?? false);
+  const haystack = [r.name, r.description, r.category, (r.tags ?? []).join(" "), r.resource].filter(Boolean).join(" ").toLowerCase();
+  if (haystack.includes(query.toLowerCase())) return true;
+  const qTokens = tokenize(query);
+  const hayTokens = new Set(tokenize(haystack));
+  return qTokens.some((t) => hayTokens.has(t));
+}
+function pickStringArray(o, ...keys) {
+  for (const k of keys) {
+    const v = o[k];
+    if (Array.isArray(v)) {
+      const arr = v.filter((x) => typeof x === "string" && x.length > 0);
+      if (arr.length) return arr;
+    } else if (typeof v === "string" && v.trim()) {
+      const arr = v.split(/[,\s]+/).filter((x) => x.length > 0);
+      if (arr.length) return arr;
+    }
+  }
+  return void 0;
 }
 function pickString(o, ...keys) {
   for (const k of keys) {
@@ -2383,6 +2530,17 @@ function appendAttribution(description) {
   const next = `${description.trimEnd()} ${REGISTER_ATTRIBUTION}`;
   return next.length <= 500 ? next : description;
 }
+function appendKeywords(description, tags) {
+  const clean = (tags ?? []).map((t) => t.trim()).filter((t) => t.length > 0);
+  if (clean.length === 0) return description;
+  const have = (description ?? "").toLowerCase();
+  const fresh = [...new Set(clean.filter((t) => !have.includes(t.toLowerCase())))];
+  if (fresh.length === 0) return description;
+  const tail = `Keywords: ${fresh.join(", ")}`;
+  if (!description) return tail;
+  const next = `${description.trimEnd()} \xB7 ${tail}`;
+  return next.length <= 500 ? next : description;
+}
 function encodeBase642(str) {
   if (typeof Buffer !== "undefined") return Buffer.from(str, "utf8").toString("base64");
   if (typeof btoa === "function" && typeof TextEncoder !== "undefined") {
@@ -2874,22 +3032,24 @@ var PipRailClient = class {
     const found = await searchOpenIndexes({
       ...opts.query !== void 0 ? { query: opts.query } : {},
       ...opts.sources ? { sources: opts.sources } : {},
-      ...opts.limit !== void 0 ? { limit: opts.limit } : {}
+      ...opts.limit !== void 0 ? { limit: opts.limit } : {},
+      ...opts.maxPrice !== void 0 ? { maxPrice: opts.maxPrice } : {},
+      ...opts.category ? { category: opts.category } : {},
+      ...opts.asset ? { asset: opts.asset } : {},
+      ...opts.minReliability !== void 0 ? { minReliability: opts.minReliability } : {},
+      ...opts.verified !== void 0 ? { verified: opts.verified } : {},
+      ...opts.paymentValid !== void 0 ? { paymentValid: opts.paymentValid } : {},
+      ...opts.sort ? { sort: opts.sort } : {},
+      ...opts.order ? { order: opts.order } : {}
     });
     const scope = opts.network ?? "self";
-    let out = found;
+    if (scope === "any") return found;
     if (scope === "self") {
       const { net } = await this.ensure();
-      out = out.filter((r) => r.rails.some((rail) => railOnNetwork(rail, (n) => net.supports(n))));
-    } else if (scope !== "any") {
-      const target = normalizeNetwork(scope);
-      out = out.filter((r) => r.rails.some((rail) => railOnNetwork(rail, (n) => n === target)));
-    }
-    if (opts.maxPrice !== void 0) {
-      const max = opts.maxPrice;
-      out = out.filter((r) => r.priceUsd === void 0 || r.priceUsd <= max);
+      return found.filter((r) => r.rails.some((rail) => railOnNetwork(rail, (n) => net.supports(n))));
     }
-    return out;
+    const target = normalizeNetwork(scope);
+    return found.filter((r) => r.rails.some((rail) => railOnNetwork(rail, (n) => n === target)));
   }
   /**
    * List a resource you run on the OPEN x402 registries, so agents can find it.
@@ -2930,6 +3090,11 @@ var PipRailClient = class {
             ...opts.asset ? { asset: opts.asset } : {},
             ...networkSlug ? { network: networkSlug } : {},
             ...opts.method ? { method: opts.method } : {},
+            ...opts.category ? { category: opts.category } : {},
+            ...opts.tags ? { tags: opts.tags } : {},
+            ...opts.provider ? { provider: opts.provider } : {},
+            ...opts.contactEmail ? { contactEmail: opts.contactEmail } : {},
+            ...opts.probeBody !== void 0 ? { probeBody: opts.probeBody } : {},
             // Attribution is default-ON; forward an explicit opt-out, else let register402Index default it.
             ...opts.attribution === false ? { attribution: false } : {}
           })
@@ -3906,6 +4071,7 @@ function buildSelfDescription(input) {
     protocol: "x402",
     version: "2",
     what: WHAT,
+    ...input.endpoint && Object.keys(input.endpoint).length > 0 ? { endpoint: input.endpoint } : {},
     pay: input.accepts.map(railOf),
     sdk: { install: BRAND.sdkInstall, snippet: BRAND.sdkSnippet },
     mcp: { run: BRAND.mcpRun, tool: "piprail_pay_request" },
@@ -3914,6 +4080,19 @@ function buildSelfDescription(input) {
     ...input.instruction ? { instruction: input.instruction } : {}
   };
 }
+function buildEndpointInfo(input) {
+  const d = input.descriptor;
+  const summary = d?.summary ?? input.description;
+  const hasInput = d?.queryParams && Object.keys(d.queryParams).length > 0;
+  const endpoint = {
+    ...summary ? { summary } : {},
+    ...d?.method ? { method: d.method.toUpperCase() } : {},
+    ...input.mimeType ? { mimeType: input.mimeType } : {},
+    ...hasInput ? { input: d.queryParams } : {},
+    ...d?.output ? { output: d.output } : {}
+  };
+  return Object.keys(endpoint).length > 0 ? endpoint : void 0;
+}
 
 // src/render.ts
 function summarizePlan(plan) {
@@ -4095,13 +4274,25 @@ function paymentTools(client) {
       parameters: {
         type: "object",
         properties: {
-          query: { type: "string", description: "Free-text topic to search for (optional)." },
+          query: {
+            type: "string",
+            description: 'Free-text topic to search for (optional). Multi-word queries are fanned out per word and results are ranked by relevance, so "crypto price feed" finds the best matches even when no single listing contains that exact phrase.'
+          },
           network: {
             type: "string",
             description: "CAIP-2 id, 'self' (your chain \u2014 default), or 'any' (all chains)."
           },
+          category: { type: "string", description: "Keep ONLY this category, e.g. 'ai', 'finance', 'data' (strict)." },
+          asset: { type: "string", description: "Keep only resources paying in this token symbol, e.g. 'USDC'." },
           maxPrice: { type: "number", description: "Drop results advertised above this USD price." },
-          limit: { type: "number", description: "Max results per index (default 20)." }
+          minReliability: { type: "number", description: "Drop results below this health score (0\u2013100); unscored pass." },
+          verified: { type: "boolean", description: "Prefer verified listings (402 Index)." },
+          sort: {
+            type: "string",
+            enum: ["relevance", "reliability", "price", "uptime", "name"],
+            description: "Ordering. Default 'relevance' with a query, else first-seen."
+          },
+          limit: { type: "number", description: "Max results to fetch per index (default 20)." }
         },
         additionalProperties: false
       },
@@ -4110,7 +4301,12 @@ function paymentTools(client) {
           const opts = {};
           if (typeof args.query === "string") opts.query = args.query;
           if (typeof args.network === "string") opts.network = args.network;
+          if (typeof args.category === "string") opts.category = args.category;
+          if (typeof args.asset === "string") opts.asset = args.asset;
           if (typeof args.maxPrice === "number") opts.maxPrice = args.maxPrice;
+          if (typeof args.minReliability === "number") opts.minReliability = args.minReliability;
+          if (typeof args.verified === "boolean") opts.verified = args.verified;
+          if (typeof args.sort === "string") opts.sort = args.sort;
           if (typeof args.limit === "number") opts.limit = args.limit;
           const found = await client.discover(opts);
           return {
@@ -4120,7 +4316,11 @@ function paymentTools(client) {
               name: r.name,
               description: r.description,
               source: r.source,
+              category: r.category,
               priceUsd: r.priceUsd,
+              reliabilityScore: r.reliabilityScore,
+              health: r.health,
+              verified: r.verified,
               networks: [...new Set(r.rails.map((rail) => rail.network))]
             }))
           };
@@ -4302,13 +4502,20 @@ function paymentTools(client) {
         properties: {
           url: { type: "string", description: "Full URL of the resource to list." },
           name: { type: "string", description: "Display name (defaults to the host)." },
-          description: { type: "string", description: "What the resource offers." },
+          description: {
+            type: "string",
+            description: "What the resource offers. Pack the words agents will search for INTO this text \u2014 index search is literal, so a keyword that isn't in the name/description won't be found."
+          },
+          category: { type: "string", description: "A category, e.g. 'ai', 'finance', 'data' \u2014 the top findability field (most listings have none)." },
+          tags: { type: "array", items: { type: "string" }, description: "Keywords; folded into the description so they're searchable." },
           priceUsd: { type: "number", description: "Advertised price in USD (metadata)." },
           network: {
             type: "string",
             description: "Network slug to advertise, e.g. 'base' (defaults to the paying chain). Set it when registering from a multi-chain wallet so the listing names the right chain."
           },
-          asset: { type: "string", description: "Payment asset symbol, e.g. 'USDC' (metadata)." }
+          asset: { type: "string", description: "Payment asset symbol, e.g. 'USDC' (metadata)." },
+          provider: { type: "string", description: "Who runs the resource (provider/org name)." },
+          contactEmail: { type: "string", description: "Contact email for the listing." }
         },
         required: ["url"],
         additionalProperties: false
@@ -4318,9 +4525,13 @@ function paymentTools(client) {
           const opts = {};
           if (typeof args.name === "string") opts.name = args.name;
           if (typeof args.description === "string") opts.description = args.description;
+          if (typeof args.category === "string") opts.category = args.category;
+          if (Array.isArray(args.tags)) opts.tags = args.tags.filter((t) => typeof t === "string");
           if (typeof args.priceUsd === "number") opts.priceUsd = args.priceUsd;
           if (typeof args.network === "string") opts.network = args.network;
           if (typeof args.asset === "string") opts.asset = args.asset;
+          if (typeof args.provider === "string") opts.provider = args.provider;
+          if (typeof args.contactEmail === "string") opts.contactEmail = args.contactEmail;
           const outcomes = await client.register(String(args.url), opts);
           return { outcomes };
         } catch (err) {
@@ -4846,9 +5057,15 @@ function createPaymentGate(options) {
     const nonce = genNonce();
     const bazaar = options.discovery ? { bazaar: buildBazaarExtension(options.discovery === true ? {} : options.discovery) } : void 0;
     const accepts = buildAccepts(specs, nonce);
+    const endpointInfo = buildEndpointInfo({
+      ...options.description ? { description: options.description } : {},
+      ...options.mimeType ? { mimeType: options.mimeType } : {},
+      ...typeof options.discovery === "object" ? { descriptor: options.discovery } : {}
+    });
     const selfDescribe = options.selfDescribe === false ? void 0 : buildSelfDescription({
       accepts,
-      instruction: describeChallenge({ x402Version: 2, resource: { url: resourceUrl }, accepts })
+      instruction: describeChallenge({ x402Version: 2, resource: { url: resourceUrl }, accepts }),
+      ...endpointInfo ? { endpoint: endpointInfo } : {}
     });
     const rejectionExt = opts?.extensions ?? {};
     const rejectionPiprail = rejectionExt.piprail ?? {};
@@ -4866,7 +5083,8 @@ function createPaymentGate(options) {
       x402Version: 2,
       resource: {
         url: resourceUrl,
-        ...options.description ? { description: options.description } : {}
+        ...options.description ? { description: options.description } : {},
+        ...options.mimeType ? { mimeType: options.mimeType } : {}
       },
       accepts,
       ...opts?.error ? { error: opts.error } : {},
@@ -4956,6 +5174,7 @@ function createPaymentGate(options) {
     return {
       url: resourceUrl,
       ...options.description ? { description: options.description } : {},
+      ...options.mimeType ? { mimeType: options.mimeType } : {},
       accepts
     };
   }
@@ -5323,8 +5542,10 @@ export {
   X402_EXACT_PERMIT2_PROXY,
   agentGuide,
   appendAttribution,
+  appendKeywords,
   buildBazaarExtension,
   buildChallengeHeader,
+  buildEndpointInfo,
   buildExactAuthorization,
   buildExactSignatureHeader,
   buildOpenApi,
@@ -5363,6 +5584,7 @@ export {
   paymentTools,
   pickAccept,
   planAcross,
+  rankResources,
   readExactDomain,
   register402Index,
   registerDriver,
@@ -5370,6 +5592,7 @@ export {
   renderLandingPage,
   requirePayment,
   resolveChain,
+  scoreResource,
   searchOpenIndexes,
   settleViaFacilitator,
   summarizePlan,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",