@piprail/sdk 1.10.0 → 1.12.0

package/dist/index.js

@@ -1305,9 +1305,47 @@ async function resolveNetwork2(opts) {
 }
 
 // src/indexes.ts
+var DIRECTORY_INFO = {
+  "402index": {
+    source: "402index",
+    review: "probe-sync",
+    auth: "none",
+    chains: null,
+    onSuccess: "pending-review",
+    readByDiscover: true,
+    caveat: "402 Index probes your URL on submit, then lists it as PENDING REVIEW \u2014 a self-registered resource is NOT in search until approved. Verify your domain on 402index.io for instant approval; otherwise it appears after manual review, so retry discover() later."
+  },
+  x402scan: {
+    source: "x402scan",
+    review: "probe-sync",
+    auth: "siwx",
+    chains: ["eip155:8453", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],
+    onSuccess: "live",
+    readByDiscover: false,
+    caveat: "x402scan lists Base/Solana only, needs one wallet signature (SIWX), and requires a resolvable input schema (from /openapi.json or the bazaar extension in the 402 body). It goes live on x402scan.com immediately on success \u2014 but discover() does NOT read x402scan, so the listing won't appear in discover() results."
+  },
+  bazaar: {
+    source: "bazaar",
+    review: "settle-coupled",
+    auth: "facilitator-only",
+    chains: null,
+    onSuccess: "not-listable",
+    readByDiscover: true,
+    caveat: "CDP Bazaar has no register endpoint \u2014 it catalogs a resource only when its own facilitator settles a payment. PipRail verifies locally with no facilitator, so a PipRail resource cannot be listed here (you can still READ Bazaar to find others). List on 402 Index or x402scan instead."
+  }
+};
+function getDirectoryInfo(source) {
+  return DIRECTORY_INFO[source];
+}
+function decorateOutcome(o) {
+  const info = DIRECTORY_INFO[o.source];
+  return { ...o, visibility: o.ok ? info.onSuccess : "not-listable", note: info.caveat };
+}
 var BAZAAR_URL = "https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources";
 var INDEX402_SEARCH = "https://402index.io/api/v1/services";
 var INDEX402_REGISTER = "https://402index.io/api/v1/register";
+var INDEX402_CLAIM = "https://402index.io/api/v1/claim";
+var INDEX402_VERIFY = "https://402index.io/api/v1/claim/verify";
 var X402SCAN_REGISTER = "https://www.x402scan.com/api/x402/registry/register";
 var USER_AGENT = "@piprail/sdk (+https://piprail.com)";
 function clientHeaders(extra = {}) {
@@ -1457,7 +1495,13 @@ async function register402Index(input) {
       body: JSON.stringify(payload)
     });
     if (res.ok) {
-      return { source: "402index", ok: true, status: res.status, detail: "Listed on 402 Index (searchable at 402index.io)." };
+      const msg = await readIndexMessage(res);
+      return {
+        source: "402index",
+        ok: true,
+        status: res.status,
+        detail: msg ?? "Registered on 402 Index \u2014 pending review (verify your domain on 402index.io for instant approval)."
+      };
     }
     const why = await readIndexError(res);
     return {
@@ -1470,6 +1514,14 @@ async function register402Index(input) {
     return { source: "402index", ok: false, detail: errMsg(err) };
   }
 }
+async function readIndexMessage(res) {
+  try {
+    const body = await res.json();
+    return typeof body.message === "string" && body.message.length > 0 ? body.message : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function readIndexError(res) {
   try {
     const body = await res.json();
@@ -1529,6 +1581,53 @@ async function registerX402Scan(input, signer) {
     return { source: "x402scan", ok: false, detail: errMsg(err) };
   }
 }
+async function claim402IndexDomain(domainOrUrl, opts = {}) {
+  const domain = hostOf(domainOrUrl);
+  try {
+    const res = await fetch(INDEX402_CLAIM, {
+      method: "POST",
+      headers: clientHeaders({ "content-type": "application/json", accept: "application/json" }),
+      body: JSON.stringify({ domain, ...opts.contactEmail ? { contact_email: opts.contactEmail } : {} })
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      return { ok: false, domain, httpStatus: res.status, detail: pickString(body, "error", "detail", "message") ?? `402 Index claim returned HTTP ${res.status}.` };
+    }
+    return {
+      ok: true,
+      domain,
+      httpStatus: res.status,
+      ...optionalString("verificationHash", pickString(body, "verification_hash")),
+      ...optionalString("verificationUrl", pickString(body, "verification_url")),
+      ...optionalString("instructions", pickString(body, "instructions"))
+    };
+  } catch (err) {
+    return { ok: false, domain, detail: errMsg(err) };
+  }
+}
+async function verify402IndexDomain(domainOrUrl) {
+  const domain = hostOf(domainOrUrl);
+  try {
+    const res = await fetch(INDEX402_VERIFY, {
+      method: "POST",
+      headers: clientHeaders({ "content-type": "application/json", accept: "application/json" }),
+      body: JSON.stringify({ domain })
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      return { ok: false, domain, httpStatus: res.status, detail: pickString(body, "error", "detail", "message") ?? `402 Index verify returned HTTP ${res.status}.` };
+    }
+    return {
+      ok: true,
+      domain,
+      httpStatus: res.status,
+      ...optionalString("status", pickString(body, "status")),
+      ...typeof body.services_count === "number" ? { servicesCount: body.services_count } : {}
+    };
+  } catch (err) {
+    return { ok: false, domain, detail: errMsg(err) };
+  }
+}
 async function readSiwxInfo(res) {
   try {
     const body = await res.json();
@@ -1908,9 +2007,15 @@ var PipRailClient = class {
    *
    * Nothing PipRail-hosted: these are third-party open directories. Never throws
    * for a read problem — an index that's down or changed simply contributes
-   * nothing. Honest caveat: index results are cross-scheme (mostly the
-   * mainstream `exact` scheme); `fetch()` pays only `onchain-proof` rails
-   * directly (pay `exact` resources with the experimental `drivers/evm/exact.ts`).
+   * nothing. Honest caveats (see {@link DIRECTORY_INFO}):
+   * - Reads **`bazaar` + `402index`** only — **NOT `x402scan`** (its reads are paid). A
+   *   resource you registered on x402scan is live there but will NOT appear here; don't
+   *   read that absence as failure. (Passing `sources:['x402scan']` explicitly yields `[]`.)
+   * - A resource just listed via {@link register} may not appear yet — 402 Index reviews
+   *   before publishing, so retry with a brief backoff if a fresh listing is missing.
+   * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
+   *   only `onchain-proof` rails directly (pay `exact` resources with the experimental
+   *   `drivers/evm/exact.ts`).
    */
   async discover(opts = {}) {
     const found = await searchOpenIndexes({
@@ -1935,12 +2040,27 @@ var PipRailClient = class {
   }
   /**
    * List a resource you run on the OPEN x402 registries, so agents can find it.
-   * Default target is **402 Index** — one POST, no auth, no signature, no payment
-   * (searchable within seconds). Add `'x402scan'` to also register via SIWX (one
-   * wallet signature; EVM + a Base/Solana rail). Returns one {@link RegisterOutcome}
-   * per target — a target the chain can't satisfy comes back `{ ok:false, detail }`,
-   * never a throw. An explicit, developer-invoked action; it moves no funds, and
-   * nothing is PipRail-hosted — you're listing on third-party open directories.
+   * Default target is **402 Index** — one POST, no auth, no signature, no payment.
+   * Add `'x402scan'` to also register via SIWX (one wallet signature; EVM + a
+   * Base/Solana rail). Returns one {@link RegisterOutcome} per target — a target the
+   * chain can't satisfy comes back `{ ok:false, detail }`, never a throw. An explicit,
+   * developer-invoked action; it moves no funds, and nothing is PipRail-hosted —
+   * you're listing on third-party open directories.
+   *
+   * **Listing is asynchronous — each outcome carries a `visibility` + `note` so an
+   * agent knows when/where the resource is findable (don't assume `ok:true` means
+   * "searchable now"):**
+   * - **402 Index** → `visibility:'pending-review'`. It probes your URL on submit, then lists it
+   *   PENDING REVIEW — not searchable until approved (verify your domain on 402index.io for instant
+   *   approval), so `discover()` returns nothing for a fresh listing until then. Retry later.
+   * - **x402scan** → `visibility:'live'`, but **`discover()` does NOT read x402scan** — the
+   *   listing is real on x402scan.com yet won't show up in `discover()`. Base/Solana only;
+   *   needs a resolvable input schema (`/openapi.json` or the `extensions.bazaar` block).
+   * - **Bazaar** → `visibility:'not-listable'` for PipRail (it lists only what its facilitator
+   *   settles; PipRail uses none). You can still READ Bazaar via {@link discover} to find others.
+   *
+   * The per-source facts live in {@link DIRECTORY_INFO} (importable) if you'd rather branch
+   * on them before calling.
    */
   async register(url, opts = {}) {
     const targets = opts.targets ?? ["402index"];
@@ -1979,7 +2099,33 @@ var PipRailClient = class {
         });
       }
     }
-    return outcomes;
+    return outcomes.map(decorateOutcome);
+  }
+  /**
+   * **402 Index domain verification, step 1 of 2.** A self-registered 402 Index
+   * listing is `pending-review` (see {@link register}); verifying your domain flips
+   * it — and every other pending listing on that domain — to APPROVED/searchable.
+   * Pass the resource URL or a bare domain; returns the `verificationHash` to serve
+   * as the entire body of `verificationUrl` (your `/.well-known/402index-verify.txt`).
+   * Then serve it and call {@link verifyDomain}. Moves no funds; never throws.
+   *
+   * ```ts
+   * const claim = await client.claimDomain('https://api.example.com/report')
+   * // serve claim.verificationHash at claim.verificationUrl, then:
+   * const res = await client.verifyDomain('api.example.com')  // → { ok:true, status:'verified' }
+   * ```
+   */
+  async claimDomain(urlOrDomain, opts = {}) {
+    return claim402IndexDomain(urlOrDomain, opts);
+  }
+  /**
+   * **402 Index domain verification, step 2 of 2.** After {@link claimDomain} and
+   * serving the hash at your `/.well-known/402index-verify.txt`, this tells 402 Index
+   * to re-fetch + approve. On success the domain's pending listings become searchable
+   * (`{ ok:true, status:'verified', servicesCount }`). Moves no funds; never throws.
+   */
+  async verifyDomain(urlOrDomain) {
+    return verify402IndexDomain(urlOrDomain);
   }
   /**
    * The discovery signer for the bound wallet (its address + a message signer),
@@ -2627,7 +2773,7 @@ function paymentTools(client) {
     },
     {
       name: "piprail_register",
-      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; searchable within seconds. Returns one outcome per index ({ source, ok, detail }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
+      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
       annotations: {
         title: "Register an x402 endpoint",
         readOnlyHint: false,
@@ -3161,6 +3307,7 @@ function buildX402DnsTxt(input) {
 export {
   CHAINS,
   ConfirmationTimeoutError,
+  DIRECTORY_INFO,
   EIP3009_TYPES,
   EXACT_NETWORK_SLUGS,
   GENERATOR,
@@ -3193,10 +3340,13 @@ export {
   buildWellKnownX402,
   buildX402DnsTxt,
   chainIdForExactNetwork,
+  claim402IndexDomain,
   createPaymentGate,
+  decorateOutcome,
   eip3009Abi,
   encodeXPaymentHeader,
   evaluatePolicy,
+  getDirectoryInfo,
   normalizeNetwork,
   parseChallenge,
   parseExactPaymentHeader,
@@ -3215,5 +3365,6 @@ export {
   searchOpenIndexes,
   settleViaFacilitator,
   toInsufficientFundsError,
-  toInvalidBody
+  toInvalidBody,
+  verify402IndexDomain
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.10.0",
+  "version": "1.12.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",