@piprail/sdk 1.10.0 → 1.12.0

package/dist/index.d.cts

@@ -216,9 +216,6 @@ type VerifyResult = {
 declare const HEADER_REQUIRED = "payment-required";
 declare const HEADER_SIGNATURE = "payment-signature";
 declare const HEADER_RESPONSE = "payment-response";
-/** Legacy x402 v1 header names. PipRail EMITS v2 (the constants above) but also
- *  READS the v1 client header and ECHOES the v1 response header, so a deprecated
- *  v1 client (still ~half the installed base) interoperates on the `exact` rail. */
 declare const HEADER_SIGNATURE_V1 = "x-payment";
 declare const HEADER_RESPONSE_V1 = "x-payment-response";
 declare function buildChallengeHeader(challenge: X402Challenge): string;
@@ -4237,6 +4234,14 @@ interface DiscoveredResource {
     /** The payment options the index advertises (best-effort, cross-scheme). */
     rails: DiscoveredRail[];
 }
+/** Where a listing stands after a register attempt — a branchable lifecycle
+ *  state so an agent doesn't have to re-derive each index's behaviour:
+ *  - `'live'`           — findable now (search it immediately).
+ *  - `'pending-review'` — accepted, but the index reviews/propagates before it's
+ *                         publicly findable; allow a short delay before `discover()`.
+ *  - `'not-listable'`   — it didn't list (a failure, or this index structurally
+ *                         can't list a PipRail resource). See `detail` + `note`. */
+type ListingVisibility = 'live' | 'pending-review' | 'not-listable';
 /** The result of trying to list a resource on one open index. */
 interface RegisterOutcome {
     source: DiscoverySource;
@@ -4247,6 +4252,14 @@ interface RegisterOutcome {
     detail?: string;
     /** A link to the listing, when the index returns one. */
     listingUrl?: string;
+    /** The lifecycle state of this listing — `'live'`, `'pending-review'`, or
+     *  `'not-listable'`. Projected from {@link DIRECTORY_INFO}; branch on this
+     *  instead of guessing how soon `discover()` will find the resource. */
+    visibility?: ListingVisibility;
+    /** A one-line, agent-readable caveat for this source (from {@link DIRECTORY_INFO})
+     *  — e.g. "402 Index reviews before publishing" or "discover() doesn't read
+     *  x402scan, so a live listing there won't appear in discover() results". */
+    note?: string;
 }
 interface SearchOpenIndexesOptions {
     /** Free-text query (filtered client-side against name/description/resource). */
@@ -4278,6 +4291,48 @@ interface RegisterInput {
      */
     attribution?: boolean;
 }
+/**
+ * Static, agent-readable lifecycle facts about one open index — the SINGLE source
+ * of truth that {@link RegisterOutcome.visibility}/`note` are projected from, and
+ * that an agent can also query directly (via {@link getDirectoryInfo}) to reason
+ * about an index BEFORE calling. Best-effort: an index can change its behaviour,
+ * so treat the timing as guidance, not an SLA.
+ */
+interface DirectoryInfo {
+    source: DiscoverySource;
+    /** How a new listing is gated: a synchronous URL probe (`402index`, `x402scan`),
+     *  or coupled to a facilitator settling a payment (`bazaar`). */
+    review: 'probe-sync' | 'settle-coupled';
+    /** Auth needed to WRITE a listing. */
+    auth: 'none' | 'siwx' | 'facilitator-only';
+    /** Chains (CAIP-2) this index will list. `null` = any chain the resource advertises. */
+    chains: readonly string[] | null;
+    /** Visibility a SUCCESSFUL listing reaches here (the steady state a non-failed
+     *  outcome maps to). */
+    onSuccess: ListingVisibility;
+    /** Whether THIS SDK's {@link PipRailClient.discover} reads this index. It reads
+     *  `bazaar` + `402index`; it does NOT read `x402scan` — so a live x402scan listing
+     *  won't appear in `discover()` results. Don't read that absence as failure. */
+    readByDiscover: boolean;
+    /** One-line caveat: why a register might fail, or what to expect afterwards. */
+    caveat: string;
+}
+/**
+ * The open directories' lifecycle, as one queryable map. An agent can branch on
+ * this without embedding directory knowledge: `DIRECTORY_INFO[source].readByDiscover`,
+ * `.chains`, `.onSuccess`, etc. {@link PipRailClient.register} projects the relevant
+ * entry onto every {@link RegisterOutcome} (`visibility` + `note`).
+ */
+declare const DIRECTORY_INFO: Readonly<Record<DiscoverySource, DirectoryInfo>>;
+/** Lifecycle facts for one open index (auth, chains, how soon a listing is
+ *  findable, whether `discover()` reads it). See {@link DIRECTORY_INFO}. The param
+ *  is the closed {@link DiscoverySource} union (TS callers are safe); a string
+ *  outside it returns `undefined` at runtime. */
+declare function getDirectoryInfo(source: DiscoverySource): DirectoryInfo;
+/** Project the static {@link DIRECTORY_INFO} lifecycle facts onto a register
+ *  outcome, so an agent gets `visibility` + `note` in the result it already holds —
+ *  no second lookup. A failed outcome is always `'not-listable'`. Idempotent. */
+declare function decorateOutcome(o: RegisterOutcome): RegisterOutcome;
 /** Normalize an index's network field to CAIP-2 when we recognise the slug;
  *  pass a value that's already CAIP-2 (`namespace:reference`) through unchanged.
  *  An unknown slug returns unchanged (no `:`), which the client treats as
@@ -4291,8 +4346,11 @@ declare function normalizeNetwork(network: string): string;
 declare function searchOpenIndexes(opts?: SearchOpenIndexesOptions): Promise<DiscoveredResource[]>;
 /**
  * Register a resource on **402 Index** — the primary, friction-free path: a
- * single POST, no auth, no signature, no payment. Searchable within seconds.
- * Returns a structured outcome; never throws for an HTTP/transport problem.
+ * single POST, no auth, no signature, no payment. A self-registered listing is
+ * **pending review** (not searchable until approved — verify your domain on
+ * 402index.io for instant approval). Returns a structured outcome; never throws
+ * for an HTTP/transport problem. NOTE: the outcome is BARE — `visibility`/`note`
+ * are added by {@link PipRailClient.register} (or call {@link decorateOutcome}).
  */
 declare function register402Index(input: RegisterInput): Promise<RegisterOutcome>;
 /**
@@ -4300,11 +4358,57 @@ declare function register402Index(input: RegisterInput): Promise<RegisterOutcome
  * EIP-4361 challenge with the merchant's own key, resend with the
  * `SIGN-IN-WITH-X` header. Facilitator-free, but **Base/Solana-only** and EVM
  * signing today. EXPERIMENTAL — the open SIWX handshake is a moving convention;
- * validate against x402scan before relying on it. Never throws.
+ * validate against x402scan before relying on it. Never throws. NOTE: returns a
+ * BARE outcome — `visibility`/`note` are added by {@link PipRailClient.register}
+ * (or call {@link decorateOutcome}).
  */
 declare function registerX402Scan(input: {
     url: string;
 }, signer: DiscoverySigner): Promise<RegisterOutcome>;
+/** What {@link claim402IndexDomain} returns — the proof to SERVE so 402 Index will
+ *  approve your domain (and flip your `pending-review` listings to searchable). */
+interface DomainClaim {
+    ok: boolean;
+    domain: string;
+    /** Serve THIS string as the entire body of `verificationUrl`. */
+    verificationHash?: string;
+    /** Where to serve it — your `https://<domain>/.well-known/402index-verify.txt`. */
+    verificationUrl?: string;
+    /** 402 Index's own human instructions. */
+    instructions?: string;
+    httpStatus?: number;
+    /** Failure reason when `ok:false`. */
+    detail?: string;
+}
+/** What {@link verify402IndexDomain} returns once the proof is in place. */
+interface DomainVerification {
+    ok: boolean;
+    domain: string;
+    /** 402 Index's status string, e.g. `'verified'`. */
+    status?: string;
+    /** How many of your pending listings were approved by the verification. */
+    servicesCount?: number;
+    httpStatus?: number;
+    detail?: string;
+}
+/**
+ * Step 1 of 402 Index domain verification: claim the host of `domainOrUrl`. 402 Index
+ * lists a self-registered resource as PENDING REVIEW; verifying the domain approves it
+ * (and every other pending listing on that domain) so it becomes searchable. Returns the
+ * `verificationHash` to serve as the entire body of `verificationUrl`
+ * (`https://<domain>/.well-known/402index-verify.txt`). Then call {@link verify402IndexDomain}.
+ * No funds move. Never throws.
+ */
+declare function claim402IndexDomain(domainOrUrl: string, opts?: {
+    contactEmail?: string;
+}): Promise<DomainClaim>;
+/**
+ * Step 2 of 402 Index domain verification: after {@link claim402IndexDomain} and serving
+ * the `verificationHash` at `verificationUrl`, tell 402 Index to re-fetch + approve. On
+ * success, the domain's pending listings become searchable (`status:'verified'`,
+ * `servicesCount` approved). No funds move. Never throws.
+ */
+declare function verify402IndexDomain(domainOrUrl: string): Promise<DomainVerification>;
 
 interface PaymentPolicy {
     /** Per-payment ceiling, human-readable (e.g. '0.10'). Compared using the
@@ -4753,21 +4857,66 @@ declare class PipRailClient {
      *
      * 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`).
      */
     discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
     /**
      * 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.
      */
     register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
+    /**
+     * **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' }
+     * ```
+     */
+    claimDomain(urlOrDomain: string, opts?: {
+        contactEmail?: string;
+    }): Promise<DomainClaim>;
+    /**
+     * **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.
+     */
+    verifyDomain(urlOrDomain: string): Promise<DomainVerification>;
     /**
      * The discovery signer for the bound wallet (its address + a message signer),
      * or `null` if the chain family doesn't support it (EVM does today). For
@@ -5619,12 +5768,21 @@ declare function buildExactAuthorization(params: BuildExactParams): Promise<{
     authorization: ExactAuthorization;
     signature: Hex;
 }>;
-/** Encode an x402 `exact` PaymentPayload into an `X-PAYMENT` header value. */
+/**
+ * Encode an x402 `exact` PaymentPayload into an `X-PAYMENT` header value — the
+ * **v1 flat shape** (`{ x402Version, scheme, network, payload }`). This is a
+ * client-side UTILITY (PipRail's own client pays only `onchain-proof`, never this);
+ * the v1 flat shape is what Coinbase's original reference emits and is still accepted
+ * by every x402 gate + facilitator, so `x402Version` defaults to `1` to stay
+ * INTERNALLY CONSISTENT with that shape (emitting `2` here would mislabel a v1 body —
+ * a proper v2 `exact` payload is the nested `accepted`-envelope shape instead). See
+ * the version-posture note in `x402.ts`.
+ */
 declare function encodeXPaymentHeader(input: {
     network: string;
     authorization: ExactAuthorization;
     signature: Hex;
-    /** x402 envelope version (Coinbase's reference uses 1). */
+    /** x402 envelope version. Defaults to `1` — consistent with this flat shape. */
     x402Version?: number;
 }): string;
 /**
@@ -5740,4 +5898,4 @@ declare function readExactDomain(publicClient: PublicClient, asset: string): Pro
     version: string;
 } | null>;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, 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 ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, 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, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, 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, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, 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, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.d.ts

@@ -216,9 +216,6 @@ type VerifyResult = {
 declare const HEADER_REQUIRED = "payment-required";
 declare const HEADER_SIGNATURE = "payment-signature";
 declare const HEADER_RESPONSE = "payment-response";
-/** Legacy x402 v1 header names. PipRail EMITS v2 (the constants above) but also
- *  READS the v1 client header and ECHOES the v1 response header, so a deprecated
- *  v1 client (still ~half the installed base) interoperates on the `exact` rail. */
 declare const HEADER_SIGNATURE_V1 = "x-payment";
 declare const HEADER_RESPONSE_V1 = "x-payment-response";
 declare function buildChallengeHeader(challenge: X402Challenge): string;
@@ -4237,6 +4234,14 @@ interface DiscoveredResource {
     /** The payment options the index advertises (best-effort, cross-scheme). */
     rails: DiscoveredRail[];
 }
+/** Where a listing stands after a register attempt — a branchable lifecycle
+ *  state so an agent doesn't have to re-derive each index's behaviour:
+ *  - `'live'`           — findable now (search it immediately).
+ *  - `'pending-review'` — accepted, but the index reviews/propagates before it's
+ *                         publicly findable; allow a short delay before `discover()`.
+ *  - `'not-listable'`   — it didn't list (a failure, or this index structurally
+ *                         can't list a PipRail resource). See `detail` + `note`. */
+type ListingVisibility = 'live' | 'pending-review' | 'not-listable';
 /** The result of trying to list a resource on one open index. */
 interface RegisterOutcome {
     source: DiscoverySource;
@@ -4247,6 +4252,14 @@ interface RegisterOutcome {
     detail?: string;
     /** A link to the listing, when the index returns one. */
     listingUrl?: string;
+    /** The lifecycle state of this listing — `'live'`, `'pending-review'`, or
+     *  `'not-listable'`. Projected from {@link DIRECTORY_INFO}; branch on this
+     *  instead of guessing how soon `discover()` will find the resource. */
+    visibility?: ListingVisibility;
+    /** A one-line, agent-readable caveat for this source (from {@link DIRECTORY_INFO})
+     *  — e.g. "402 Index reviews before publishing" or "discover() doesn't read
+     *  x402scan, so a live listing there won't appear in discover() results". */
+    note?: string;
 }
 interface SearchOpenIndexesOptions {
     /** Free-text query (filtered client-side against name/description/resource). */
@@ -4278,6 +4291,48 @@ interface RegisterInput {
      */
     attribution?: boolean;
 }
+/**
+ * Static, agent-readable lifecycle facts about one open index — the SINGLE source
+ * of truth that {@link RegisterOutcome.visibility}/`note` are projected from, and
+ * that an agent can also query directly (via {@link getDirectoryInfo}) to reason
+ * about an index BEFORE calling. Best-effort: an index can change its behaviour,
+ * so treat the timing as guidance, not an SLA.
+ */
+interface DirectoryInfo {
+    source: DiscoverySource;
+    /** How a new listing is gated: a synchronous URL probe (`402index`, `x402scan`),
+     *  or coupled to a facilitator settling a payment (`bazaar`). */
+    review: 'probe-sync' | 'settle-coupled';
+    /** Auth needed to WRITE a listing. */
+    auth: 'none' | 'siwx' | 'facilitator-only';
+    /** Chains (CAIP-2) this index will list. `null` = any chain the resource advertises. */
+    chains: readonly string[] | null;
+    /** Visibility a SUCCESSFUL listing reaches here (the steady state a non-failed
+     *  outcome maps to). */
+    onSuccess: ListingVisibility;
+    /** Whether THIS SDK's {@link PipRailClient.discover} reads this index. It reads
+     *  `bazaar` + `402index`; it does NOT read `x402scan` — so a live x402scan listing
+     *  won't appear in `discover()` results. Don't read that absence as failure. */
+    readByDiscover: boolean;
+    /** One-line caveat: why a register might fail, or what to expect afterwards. */
+    caveat: string;
+}
+/**
+ * The open directories' lifecycle, as one queryable map. An agent can branch on
+ * this without embedding directory knowledge: `DIRECTORY_INFO[source].readByDiscover`,
+ * `.chains`, `.onSuccess`, etc. {@link PipRailClient.register} projects the relevant
+ * entry onto every {@link RegisterOutcome} (`visibility` + `note`).
+ */
+declare const DIRECTORY_INFO: Readonly<Record<DiscoverySource, DirectoryInfo>>;
+/** Lifecycle facts for one open index (auth, chains, how soon a listing is
+ *  findable, whether `discover()` reads it). See {@link DIRECTORY_INFO}. The param
+ *  is the closed {@link DiscoverySource} union (TS callers are safe); a string
+ *  outside it returns `undefined` at runtime. */
+declare function getDirectoryInfo(source: DiscoverySource): DirectoryInfo;
+/** Project the static {@link DIRECTORY_INFO} lifecycle facts onto a register
+ *  outcome, so an agent gets `visibility` + `note` in the result it already holds —
+ *  no second lookup. A failed outcome is always `'not-listable'`. Idempotent. */
+declare function decorateOutcome(o: RegisterOutcome): RegisterOutcome;
 /** Normalize an index's network field to CAIP-2 when we recognise the slug;
  *  pass a value that's already CAIP-2 (`namespace:reference`) through unchanged.
  *  An unknown slug returns unchanged (no `:`), which the client treats as
@@ -4291,8 +4346,11 @@ declare function normalizeNetwork(network: string): string;
 declare function searchOpenIndexes(opts?: SearchOpenIndexesOptions): Promise<DiscoveredResource[]>;
 /**
  * Register a resource on **402 Index** — the primary, friction-free path: a
- * single POST, no auth, no signature, no payment. Searchable within seconds.
- * Returns a structured outcome; never throws for an HTTP/transport problem.
+ * single POST, no auth, no signature, no payment. A self-registered listing is
+ * **pending review** (not searchable until approved — verify your domain on
+ * 402index.io for instant approval). Returns a structured outcome; never throws
+ * for an HTTP/transport problem. NOTE: the outcome is BARE — `visibility`/`note`
+ * are added by {@link PipRailClient.register} (or call {@link decorateOutcome}).
  */
 declare function register402Index(input: RegisterInput): Promise<RegisterOutcome>;
 /**
@@ -4300,11 +4358,57 @@ declare function register402Index(input: RegisterInput): Promise<RegisterOutcome
  * EIP-4361 challenge with the merchant's own key, resend with the
  * `SIGN-IN-WITH-X` header. Facilitator-free, but **Base/Solana-only** and EVM
  * signing today. EXPERIMENTAL — the open SIWX handshake is a moving convention;
- * validate against x402scan before relying on it. Never throws.
+ * validate against x402scan before relying on it. Never throws. NOTE: returns a
+ * BARE outcome — `visibility`/`note` are added by {@link PipRailClient.register}
+ * (or call {@link decorateOutcome}).
  */
 declare function registerX402Scan(input: {
     url: string;
 }, signer: DiscoverySigner): Promise<RegisterOutcome>;
+/** What {@link claim402IndexDomain} returns — the proof to SERVE so 402 Index will
+ *  approve your domain (and flip your `pending-review` listings to searchable). */
+interface DomainClaim {
+    ok: boolean;
+    domain: string;
+    /** Serve THIS string as the entire body of `verificationUrl`. */
+    verificationHash?: string;
+    /** Where to serve it — your `https://<domain>/.well-known/402index-verify.txt`. */
+    verificationUrl?: string;
+    /** 402 Index's own human instructions. */
+    instructions?: string;
+    httpStatus?: number;
+    /** Failure reason when `ok:false`. */
+    detail?: string;
+}
+/** What {@link verify402IndexDomain} returns once the proof is in place. */
+interface DomainVerification {
+    ok: boolean;
+    domain: string;
+    /** 402 Index's status string, e.g. `'verified'`. */
+    status?: string;
+    /** How many of your pending listings were approved by the verification. */
+    servicesCount?: number;
+    httpStatus?: number;
+    detail?: string;
+}
+/**
+ * Step 1 of 402 Index domain verification: claim the host of `domainOrUrl`. 402 Index
+ * lists a self-registered resource as PENDING REVIEW; verifying the domain approves it
+ * (and every other pending listing on that domain) so it becomes searchable. Returns the
+ * `verificationHash` to serve as the entire body of `verificationUrl`
+ * (`https://<domain>/.well-known/402index-verify.txt`). Then call {@link verify402IndexDomain}.
+ * No funds move. Never throws.
+ */
+declare function claim402IndexDomain(domainOrUrl: string, opts?: {
+    contactEmail?: string;
+}): Promise<DomainClaim>;
+/**
+ * Step 2 of 402 Index domain verification: after {@link claim402IndexDomain} and serving
+ * the `verificationHash` at `verificationUrl`, tell 402 Index to re-fetch + approve. On
+ * success, the domain's pending listings become searchable (`status:'verified'`,
+ * `servicesCount` approved). No funds move. Never throws.
+ */
+declare function verify402IndexDomain(domainOrUrl: string): Promise<DomainVerification>;
 
 interface PaymentPolicy {
     /** Per-payment ceiling, human-readable (e.g. '0.10'). Compared using the
@@ -4753,21 +4857,66 @@ declare class PipRailClient {
      *
      * 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`).
      */
     discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
     /**
      * 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.
      */
     register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
+    /**
+     * **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' }
+     * ```
+     */
+    claimDomain(urlOrDomain: string, opts?: {
+        contactEmail?: string;
+    }): Promise<DomainClaim>;
+    /**
+     * **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.
+     */
+    verifyDomain(urlOrDomain: string): Promise<DomainVerification>;
     /**
      * The discovery signer for the bound wallet (its address + a message signer),
      * or `null` if the chain family doesn't support it (EVM does today). For
@@ -5619,12 +5768,21 @@ declare function buildExactAuthorization(params: BuildExactParams): Promise<{
     authorization: ExactAuthorization;
     signature: Hex;
 }>;
-/** Encode an x402 `exact` PaymentPayload into an `X-PAYMENT` header value. */
+/**
+ * Encode an x402 `exact` PaymentPayload into an `X-PAYMENT` header value — the
+ * **v1 flat shape** (`{ x402Version, scheme, network, payload }`). This is a
+ * client-side UTILITY (PipRail's own client pays only `onchain-proof`, never this);
+ * the v1 flat shape is what Coinbase's original reference emits and is still accepted
+ * by every x402 gate + facilitator, so `x402Version` defaults to `1` to stay
+ * INTERNALLY CONSISTENT with that shape (emitting `2` here would mislabel a v1 body —
+ * a proper v2 `exact` payload is the nested `accepted`-envelope shape instead). See
+ * the version-posture note in `x402.ts`.
+ */
 declare function encodeXPaymentHeader(input: {
     network: string;
     authorization: ExactAuthorization;
     signature: Hex;
-    /** x402 envelope version (Coinbase's reference uses 1). */
+    /** x402 envelope version. Defaults to `1` — consistent with this flat shape. */
     x402Version?: number;
 }): string;
 /**
@@ -5740,4 +5898,4 @@ declare function readExactDomain(publicClient: PublicClient, asset: string): Pro
     version: string;
 } | null>;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, 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 ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, 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, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, 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, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, 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, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };