@piprail/sdk 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.20.0] — 2026-06-11 — discovery hardening: conformance-locked, accurate timing, PipRail-attributed
+
+A minor release focused on the discovery/registration subsystem — verified live against the real
+402 Index + the deployed demo's wire, then locked as a contract. No payment-path change; the lazy-chunk
+invariant holds.
+
+### Changed — registration attribution is now ON by default (opt-out)
+- `client.register()` / `register402Index()` now attribute the listing to PipRail by default: a
+  `via: '@piprail/sdk'` provenance field **plus** a tasteful `· Built with @piprail/sdk` suffix on the
+  **description** (the one field an index displays) — the same unobtrusive "Made with X" marker as the
+  OpenAPI `x-generator`. It's metadata only (never changes how a resource is paid, ranked, or found),
+  is **deduped** (never double-stamps a description already naming PipRail), never fabricates a missing
+  description, and is **length-guarded**. **Opt out with `attribution: false`.** (Was opt-in/off before
+  — this is the one default change in the release; everything else is additive.)
+- New pure exports: **`appendAttribution(description)`** and **`REGISTER_ATTRIBUTION`**.
+
+### Fixed — registration timing/visibility now matches reality
+- The 402 Index caveat + register `detail` overstated the gate ("not searchable until approved"). Live
+  evidence (the demo is self-registered, `domain_verified: 0`, yet fully searchable) shows a self-
+  registered listing becomes searchable once it passes 402 Index's automated health + payment-validity
+  checks — no domain verification required. Domain verification is the **instant, guaranteed** path
+  (+ a verified badge). Wording corrected across `DIRECTORY_INFO`, the docs, and the llms files.
+
+### Added — an x402 conformance contract (test)
+- `test/discovery-conformance.test.ts` encodes, as executable predicates, the x402 v2 PaymentRequirements
+  envelope (CAIP-2 networks, atomic-unit string amounts, the EIP-712 domain on an `exact` rail) **and**
+  x402scan's `validateResource` gate (HTTPS · v2 · non-empty accepts · resolvable input schema · ≥1
+  Base/Solana rail), asserted against the live demo's captured wire and the SDK's own generated output —
+  so a regression that would make a PipRail endpoint un-listable fails CI.
+
 ## [1.19.0] — 2026-06-11 — gasless `exact` on 3 more chains (Monad · zkSync Era · Injective)
 
 A minor, fully additive release — defaults byte-identical (`exact` stays opt-in), no new dependency,

package/dist/index.cjs

@@ -1881,7 +1881,7 @@ var DIRECTORY_INFO = {
     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."
+    caveat: "402 Index probes your URL on submit (rejecting anything that does not return a real 402), then lists it \u2014 a self-registered resource becomes searchable once it passes automated health + payment-validity checks, with NO domain verification required (observed live: searchable within ~2 days for a healthy endpoint). Verify your domain on 402index.io for instant, guaranteed approval + a verified badge, which also flips every pending listing on that domain live at once."
   },
   x402scan: {
     source: "x402scan",
@@ -2046,16 +2046,18 @@ function railFrom402IndexFields(o) {
 }
 async function register402Index(input) {
   try {
+    const attributionOn = input.attribution !== false;
+    const description = attributionOn ? appendAttribution(input.description) : input.description;
     const payload = {
       url: input.url,
       name: _nullishCoalesce(input.name, () => ( hostOf(input.url))),
       protocol: "x402",
-      ...input.description ? { description: input.description } : {},
+      ...description ? { description } : {},
       ...typeof input.priceUsd === "number" ? { price_usd: input.priceUsd } : {},
       ...input.asset ? { payment_asset: input.asset } : {},
       ...input.network ? { payment_network: input.network } : {},
       ...input.method ? { http_method: input.method.toUpperCase() } : {},
-      ...input.attribution ? { via: "@piprail/sdk" } : {}
+      ...attributionOn ? { via: "@piprail/sdk" } : {}
     };
     const res = await fetch(INDEX402_REGISTER, {
       method: "POST",
@@ -2071,7 +2073,7 @@ async function register402Index(input) {
         ok: true,
         status: res.status,
         ...live ? { visibility: "live" } : {},
-        detail: _nullishCoalesce(msg, () => ( (live ? "Registered + live on 402 Index (domain verified)." : "Registered on 402 Index \u2014 pending review (verify your domain on 402index.io for instant approval).")))
+        detail: _nullishCoalesce(msg, () => ( (live ? "Registered + live on 402 Index (domain verified)." : "Registered on 402 Index \u2014 probed on submit, then searchable once it passes automated health + payment checks (verify your domain on 402index.io for instant approval + a verified badge).")))
       };
     }
     const why = await readIndexError(res);
@@ -2302,6 +2304,13 @@ function hostOf(url) {
 function errMsg(err) {
   return err instanceof Error ? err.message : String(err);
 }
+var REGISTER_ATTRIBUTION = "\xB7 Built with @piprail/sdk";
+function appendAttribution(description) {
+  if (!description) return description;
+  if (/piprail/i.test(description)) return description;
+  const next = `${description.trimEnd()} ${REGISTER_ATTRIBUTION}`;
+  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") {
@@ -2823,7 +2832,8 @@ var PipRailClient = (_class2 = class {
             ...opts.asset ? { asset: opts.asset } : {},
             ...networkSlug ? { network: networkSlug } : {},
             ...opts.method ? { method: opts.method } : {},
-            ...opts.attribution ? { attribution: true } : {}
+            // Attribution is default-ON; forward an explicit opt-out, else let register402Index default it.
+            ...opts.attribution === false ? { attribution: false } : {}
           })
         );
       } else if (target === "x402scan") {
@@ -4682,4 +4692,6 @@ async function deliverReceipt(receipt, options) {
 
 
 
-exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkPA6YD3HLcjs.ConfirmationTimeoutError; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.HEADER_REQUIRED = HEADER_REQUIRED; exports.HEADER_RESPONSE = HEADER_RESPONSE; exports.HEADER_RESPONSE_V1 = HEADER_RESPONSE_V1; exports.HEADER_SIGNATURE = HEADER_SIGNATURE; exports.HEADER_SIGNATURE_V1 = HEADER_SIGNATURE_V1; exports.InsufficientFundsError = _chunkPA6YD3HLcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkPA6YD3HLcjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkPA6YD3HLcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkPA6YD3HLcjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkPA6YD3HLcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkPA6YD3HLcjs.NonReplayableBodyError; exports.PERMIT2_ADDRESS = PERMIT2_ADDRESS; exports.PERMIT2_PROXY_CHAIN_IDS = PERMIT2_PROXY_CHAIN_IDS; exports.PERMIT2_WITNESS_TYPES = PERMIT2_WITNESS_TYPES; exports.PIPRAIL_AGENT_GUIDE = PIPRAIL_AGENT_GUIDE; exports.PaymentDeclinedError = _chunkPA6YD3HLcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkPA6YD3HLcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkPA6YD3HLcjs.PipRailError; exports.RecipientNotReadyError = _chunkPA6YD3HLcjs.RecipientNotReadyError; exports.SettlementError = _chunkPA6YD3HLcjs.SettlementError; exports.UnknownTokenError = _chunkPA6YD3HLcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkPA6YD3HLcjs.UnsupportedNetworkError; exports.UnsupportedSchemeError = _chunkPA6YD3HLcjs.UnsupportedSchemeError; exports.WrongChainError = _chunkPA6YD3HLcjs.WrongChainError; exports.WrongFamilyError = _chunkPA6YD3HLcjs.WrongFamilyError; exports.X402_EXACT_PERMIT2_PROXY = X402_EXACT_PERMIT2_PROXY; exports.agentGuide = agentGuide; exports.buildBazaarExtension = buildBazaarExtension; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildExactSignatureHeader = buildExactSignatureHeader; exports.buildOpenApi = buildOpenApi; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.claim402IndexDomain = claim402IndexDomain; exports.classifyChallenge = classifyChallenge; exports.createPaymentGate = createPaymentGate; exports.decorateOutcome = decorateOutcome; exports.deliverReceipt = deliverReceipt; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.explainDecline = explainDecline; exports.formatSpendReport = formatSpendReport; exports.getDirectoryInfo = getDirectoryInfo; exports.isPermit2ProxyChain = isPermit2ProxyChain; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSettleResponse = parseSettleResponse; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.readExactDomain = readExactDomain; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.summarizePlan = summarizePlan; exports.toInsufficientFundsError = _chunkPA6YD3HLcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody; exports.verify402IndexDomain = verify402IndexDomain;
+
+
+exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkPA6YD3HLcjs.ConfirmationTimeoutError; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.HEADER_REQUIRED = HEADER_REQUIRED; exports.HEADER_RESPONSE = HEADER_RESPONSE; exports.HEADER_RESPONSE_V1 = HEADER_RESPONSE_V1; exports.HEADER_SIGNATURE = HEADER_SIGNATURE; exports.HEADER_SIGNATURE_V1 = HEADER_SIGNATURE_V1; exports.InsufficientFundsError = _chunkPA6YD3HLcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkPA6YD3HLcjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkPA6YD3HLcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkPA6YD3HLcjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkPA6YD3HLcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkPA6YD3HLcjs.NonReplayableBodyError; exports.PERMIT2_ADDRESS = PERMIT2_ADDRESS; exports.PERMIT2_PROXY_CHAIN_IDS = PERMIT2_PROXY_CHAIN_IDS; exports.PERMIT2_WITNESS_TYPES = PERMIT2_WITNESS_TYPES; exports.PIPRAIL_AGENT_GUIDE = PIPRAIL_AGENT_GUIDE; exports.PaymentDeclinedError = _chunkPA6YD3HLcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkPA6YD3HLcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkPA6YD3HLcjs.PipRailError; exports.REGISTER_ATTRIBUTION = REGISTER_ATTRIBUTION; exports.RecipientNotReadyError = _chunkPA6YD3HLcjs.RecipientNotReadyError; exports.SettlementError = _chunkPA6YD3HLcjs.SettlementError; exports.UnknownTokenError = _chunkPA6YD3HLcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkPA6YD3HLcjs.UnsupportedNetworkError; exports.UnsupportedSchemeError = _chunkPA6YD3HLcjs.UnsupportedSchemeError; exports.WrongChainError = _chunkPA6YD3HLcjs.WrongChainError; exports.WrongFamilyError = _chunkPA6YD3HLcjs.WrongFamilyError; exports.X402_EXACT_PERMIT2_PROXY = X402_EXACT_PERMIT2_PROXY; exports.agentGuide = agentGuide; exports.appendAttribution = appendAttribution; exports.buildBazaarExtension = buildBazaarExtension; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildExactSignatureHeader = buildExactSignatureHeader; exports.buildOpenApi = buildOpenApi; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.claim402IndexDomain = claim402IndexDomain; exports.classifyChallenge = classifyChallenge; exports.createPaymentGate = createPaymentGate; exports.decorateOutcome = decorateOutcome; exports.deliverReceipt = deliverReceipt; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.explainDecline = explainDecline; exports.formatSpendReport = formatSpendReport; exports.getDirectoryInfo = getDirectoryInfo; exports.isPermit2ProxyChain = isPermit2ProxyChain; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSettleResponse = parseSettleResponse; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.readExactDomain = readExactDomain; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.summarizePlan = summarizePlan; exports.toInsufficientFundsError = _chunkPA6YD3HLcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody; exports.verify402IndexDomain = verify402IndexDomain;

package/dist/index.d.cts

@@ -4472,11 +4472,14 @@ interface RegisterInput {
     /** HTTP method the resource answers on. Default 'GET'. */
     method?: string;
     /**
-     * Opt-in (default off): add a `via: '@piprail/sdk'` tag to the listing payload. It's the
-     * MERCHANT's listing on a third-party index, so we never tag it by default; and it's
-     * **best-effort** — an index may ignore an unrecognised field. The reliable, always-on
-     * attribution is the `User-Agent` on the request + the `x-generator` stamp in your
-     * emitted `/openapi.json`. Off by default keeps your listing clean and can't be seen as spam.
+     * Attribute the listing to PipRail. **Default ON** (set `false` to opt out). When on, the
+     * payload gets a `via: '@piprail/sdk'` provenance field AND a compact `· Built with
+     * @piprail/sdk` suffix on the description (see {@link appendAttribution}) — the one field an
+     * index displays, so the listing is *visibly* built with PipRail as it spreads, the same
+     * unobtrusive "Made with X" marker as the `/openapi.json` `x-generator`. It's metadata only:
+     * never changes how the resource is paid or ranked, never double-stamps a description that
+     * already mentions PipRail, and never fabricates one you didn't provide. The `User-Agent`
+     * carries PipRail on every request regardless.
      */
     attribution?: boolean;
 }
@@ -4603,6 +4606,16 @@ declare function claim402IndexDomain(domainOrUrl: string, opts?: {
  * `servicesCount` approved). No funds move. Never throws.
  */
 declare function verify402IndexDomain(domainOrUrl: string): Promise<DomainVerification>;
+/** The compact "Made with X" marker {@link appendAttribution} adds to a listing's
+ *  description by default (the elegant, universally-accepted Swagger/Hugo pattern).
+ *  Middot-separated so it reads as metadata, never as part of the merchant's prose. */
+declare const REGISTER_ATTRIBUTION = "\u00B7 Built with @piprail/sdk";
+/** Append {@link REGISTER_ATTRIBUTION} to a listing description — *tastefully*. Pure.
+ *  Returns the description unchanged when it's absent (we never fabricate one), already
+ *  mentions PipRail (never double-stamp), or the result would exceed a sane listing cap
+ *  (≤ 500 chars). This is the only attribution an index actually DISPLAYS, so it's how a
+ *  registered listing stays visibly "built with PipRail" — opt out with `attribution:false`. */
+declare function appendAttribution(description: string | undefined): string | undefined;
 
 interface PaymentPolicy {
     /** Per-payment ceiling, human-readable (e.g. '0.10'). Compared using the
@@ -5105,11 +5118,12 @@ interface RegisterOptions {
      */
     targets?: DiscoverySource[];
     /**
-     * Opt-in (default off): tag the listing as built with PipRail (`via: '@piprail/sdk'`).
-     * It's a third-party listing, so we never tag it by default — and it's best-effort (the
-     * index may ignore the field). The always-on, reliable attribution is the request
-     * `User-Agent` + the `x-generator` stamp in your emitted `/openapi.json` (see
-     * `buildOpenApi`). Leave off unless you specifically want the listing tagged.
+     * Attribute the listing to PipRail. **Default ON** (set `false` to opt out). When on, the
+     * listing gets a `via: '@piprail/sdk'` provenance field plus a compact `· Built with
+     * @piprail/sdk` suffix on the description — the same unobtrusive "Made with X" marker as the
+     * `/openapi.json` `x-generator`. Metadata only: it never changes how the resource is paid or
+     * ranked, never double-stamps a description that already names PipRail, and never fabricates
+     * one. The request `User-Agent` carries PipRail regardless.
      */
     attribution?: boolean;
 }
@@ -6685,4 +6699,4 @@ declare const PERMIT2_WITNESS_TYPES: {
     }];
 };
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.d.ts

@@ -4472,11 +4472,14 @@ interface RegisterInput {
     /** HTTP method the resource answers on. Default 'GET'. */
     method?: string;
     /**
-     * Opt-in (default off): add a `via: '@piprail/sdk'` tag to the listing payload. It's the
-     * MERCHANT's listing on a third-party index, so we never tag it by default; and it's
-     * **best-effort** — an index may ignore an unrecognised field. The reliable, always-on
-     * attribution is the `User-Agent` on the request + the `x-generator` stamp in your
-     * emitted `/openapi.json`. Off by default keeps your listing clean and can't be seen as spam.
+     * Attribute the listing to PipRail. **Default ON** (set `false` to opt out). When on, the
+     * payload gets a `via: '@piprail/sdk'` provenance field AND a compact `· Built with
+     * @piprail/sdk` suffix on the description (see {@link appendAttribution}) — the one field an
+     * index displays, so the listing is *visibly* built with PipRail as it spreads, the same
+     * unobtrusive "Made with X" marker as the `/openapi.json` `x-generator`. It's metadata only:
+     * never changes how the resource is paid or ranked, never double-stamps a description that
+     * already mentions PipRail, and never fabricates one you didn't provide. The `User-Agent`
+     * carries PipRail on every request regardless.
      */
     attribution?: boolean;
 }
@@ -4603,6 +4606,16 @@ declare function claim402IndexDomain(domainOrUrl: string, opts?: {
  * `servicesCount` approved). No funds move. Never throws.
  */
 declare function verify402IndexDomain(domainOrUrl: string): Promise<DomainVerification>;
+/** The compact "Made with X" marker {@link appendAttribution} adds to a listing's
+ *  description by default (the elegant, universally-accepted Swagger/Hugo pattern).
+ *  Middot-separated so it reads as metadata, never as part of the merchant's prose. */
+declare const REGISTER_ATTRIBUTION = "\u00B7 Built with @piprail/sdk";
+/** Append {@link REGISTER_ATTRIBUTION} to a listing description — *tastefully*. Pure.
+ *  Returns the description unchanged when it's absent (we never fabricate one), already
+ *  mentions PipRail (never double-stamp), or the result would exceed a sane listing cap
+ *  (≤ 500 chars). This is the only attribution an index actually DISPLAYS, so it's how a
+ *  registered listing stays visibly "built with PipRail" — opt out with `attribution:false`. */
+declare function appendAttribution(description: string | undefined): string | undefined;
 
 interface PaymentPolicy {
     /** Per-payment ceiling, human-readable (e.g. '0.10'). Compared using the
@@ -5105,11 +5118,12 @@ interface RegisterOptions {
      */
     targets?: DiscoverySource[];
     /**
-     * Opt-in (default off): tag the listing as built with PipRail (`via: '@piprail/sdk'`).
-     * It's a third-party listing, so we never tag it by default — and it's best-effort (the
-     * index may ignore the field). The always-on, reliable attribution is the request
-     * `User-Agent` + the `x-generator` stamp in your emitted `/openapi.json` (see
-     * `buildOpenApi`). Leave off unless you specifically want the listing tagged.
+     * Attribute the listing to PipRail. **Default ON** (set `false` to opt out). When on, the
+     * listing gets a `via: '@piprail/sdk'` provenance field plus a compact `· Built with
+     * @piprail/sdk` suffix on the description — the same unobtrusive "Made with X" marker as the
+     * `/openapi.json` `x-generator`. Metadata only: it never changes how the resource is paid or
+     * ranked, never double-stamps a description that already names PipRail, and never fabricates
+     * one. The request `User-Agent` carries PipRail regardless.
      */
     attribution?: boolean;
 }
@@ -6685,4 +6699,4 @@ declare const PERMIT2_WITNESS_TYPES: {
     }];
 };
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.js

@@ -1881,7 +1881,7 @@ var DIRECTORY_INFO = {
     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."
+    caveat: "402 Index probes your URL on submit (rejecting anything that does not return a real 402), then lists it \u2014 a self-registered resource becomes searchable once it passes automated health + payment-validity checks, with NO domain verification required (observed live: searchable within ~2 days for a healthy endpoint). Verify your domain on 402index.io for instant, guaranteed approval + a verified badge, which also flips every pending listing on that domain live at once."
   },
   x402scan: {
     source: "x402scan",
@@ -2046,16 +2046,18 @@ function railFrom402IndexFields(o) {
 }
 async function register402Index(input) {
   try {
+    const attributionOn = input.attribution !== false;
+    const description = attributionOn ? appendAttribution(input.description) : input.description;
     const payload = {
       url: input.url,
       name: input.name ?? hostOf(input.url),
       protocol: "x402",
-      ...input.description ? { description: input.description } : {},
+      ...description ? { description } : {},
       ...typeof input.priceUsd === "number" ? { price_usd: input.priceUsd } : {},
       ...input.asset ? { payment_asset: input.asset } : {},
       ...input.network ? { payment_network: input.network } : {},
       ...input.method ? { http_method: input.method.toUpperCase() } : {},
-      ...input.attribution ? { via: "@piprail/sdk" } : {}
+      ...attributionOn ? { via: "@piprail/sdk" } : {}
     };
     const res = await fetch(INDEX402_REGISTER, {
       method: "POST",
@@ -2071,7 +2073,7 @@ async function register402Index(input) {
         ok: true,
         status: res.status,
         ...live ? { visibility: "live" } : {},
-        detail: msg ?? (live ? "Registered + live on 402 Index (domain verified)." : "Registered on 402 Index \u2014 pending review (verify your domain on 402index.io for instant approval).")
+        detail: msg ?? (live ? "Registered + live on 402 Index (domain verified)." : "Registered on 402 Index \u2014 probed on submit, then searchable once it passes automated health + payment checks (verify your domain on 402index.io for instant approval + a verified badge).")
       };
     }
     const why = await readIndexError(res);
@@ -2302,6 +2304,13 @@ function hostOf(url) {
 function errMsg(err) {
   return err instanceof Error ? err.message : String(err);
 }
+var REGISTER_ATTRIBUTION = "\xB7 Built with @piprail/sdk";
+function appendAttribution(description) {
+  if (!description) return description;
+  if (/piprail/i.test(description)) return description;
+  const next = `${description.trimEnd()} ${REGISTER_ATTRIBUTION}`;
+  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") {
@@ -2823,7 +2832,8 @@ var PipRailClient = class {
             ...opts.asset ? { asset: opts.asset } : {},
             ...networkSlug ? { network: networkSlug } : {},
             ...opts.method ? { method: opts.method } : {},
-            ...opts.attribution ? { attribution: true } : {}
+            // Attribution is default-ON; forward an explicit opt-out, else let register402Index default it.
+            ...opts.attribution === false ? { attribution: false } : {}
           })
         );
       } else if (target === "x402scan") {
@@ -4629,6 +4639,7 @@ export {
   PaymentTimeoutError,
   PipRailClient,
   PipRailError,
+  REGISTER_ATTRIBUTION,
   RecipientNotReadyError,
   SettlementError,
   UnknownTokenError,
@@ -4638,6 +4649,7 @@ export {
   WrongFamilyError,
   X402_EXACT_PERMIT2_PROXY,
   agentGuide,
+  appendAttribution,
   buildBazaarExtension,
   buildChallengeHeader,
   buildExactAuthorization,

package/package.json

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