@toon-protocol/client 0.14.11 → 0.15.0

package/dist/index.d.ts

@@ -508,6 +508,35 @@ interface RequestBlobStorageResult {
  * @returns `{ success, txId?, eventId?, error? }`.
  */
 declare function requestBlobStorage(client: ToonClient, secretKey: Uint8Array, params: RequestBlobStorageParams): Promise<RequestBlobStorageResult>;
+/**
+ * Extract the Arweave tx ID from the FULFILL `data` of a successful blob upload.
+ *
+ * The deployed payment-proxy returns the DVM's verbatim HTTP/1.1 response inside
+ * the FULFILL `data`. For a successful single-packet upload that response is:
+ *
+ *   HTTP/1.1 200 OK\r\n
+ *   content-length: 189\r\n
+ *   \r\n
+ *   {"accept":true,"txId":"<43-char base64url>","data":"<base64 of txId>",...}
+ *
+ * We parse the HTTP envelope, fail on a non-2xx status or `accept:false`, then
+ * read `txId` (preferred) from the JSON body — falling back to base64-decoding
+ * the `data` field when `txId` is absent.
+ *
+ * LEGACY FALLBACK: older / non-proxy providers returned the bare tx ID as
+ * `base64(utf8(txId))` directly in the FULFILL data (no HTTP envelope). When the
+ * payload is not HTTP-enveloped we preserve that original decode so non-HTTP
+ * FULFILLs do not regress.
+ *
+ * Exported for callers that drive `publishEvent` directly with a hand-built
+ * kind:5094 event (e.g. git-object uploads carrying Git-SHA/Git-Type/Repo
+ * tags, toon-client#227) and need the same FULFILL→txId decode this helper
+ * applies.
+ *
+ * @throws {Error} If the response is non-2xx, `accept:false`, the body is not
+ *   parseable JSON, or no valid Arweave tx ID can be extracted.
+ */
+declare function extractArweaveTxId(base64Data: string): string;
 
 interface BtpRuntimeClientConfig {
     btpUrl: string;
@@ -1373,6 +1402,26 @@ declare class ConnectorError extends ToonClientError {
 declare class ValidationError extends ToonClientError {
     constructor(message: string, cause?: Error);
 }
+/**
+ * Thrown when the one-time on-chain payment-channel OPEN reverts because the
+ * local settlement wallet has no native gas to pay for its own
+ * approve/openChannel/setTotalDeposit transactions. This is the channel OPEN
+ * only — per-write settlement rides ILP-over-HTTP and never spends gas. We
+ * remap ONLY this case so callers get an actionable message (fund the wallet)
+ * instead of the raw viem "...exceeds the balance of the account" string
+ * (toon-meta#65). Retryable once the wallet is funded; the underlying viem/RPC
+ * error is preserved as `cause`.
+ */
+declare class ChannelFundingError extends ToonClientError {
+    readonly retryable = true;
+    constructor(message: string, cause?: Error);
+}
+/**
+ * True when `err` (or any error in its nested `cause` chain) is an
+ * insufficient-native-gas revert. viem wraps the node error one or more levels
+ * deep, so the whole chain is flattened and scanned.
+ */
+declare function isInsufficientGasError(err: unknown): boolean;
 
 /**
  * Configuration options for HttpRuntimeClient.
@@ -2316,14 +2365,22 @@ declare class OnChainChannelClient implements ConnectorChannelClient {
      */
     private openMinaChannel;
     /**
-     * Opens an EVM payment channel on-chain.
+     * Opens an EVM payment channel on-chain, remapping the one-time
+     * insufficient-native-gas revert into an actionable {@link ChannelFundingError}
+     * so callers surface "fund the wallet" instead of the raw viem
+     * "...exceeds the balance of the account" string (toon-meta#65). Only the gas
+     * case is remapped; every other error propagates unchanged.
+     */
+    private openEvmChannel;
+    /**
+     * Raw EVM channel-open (no gas-error remapping — see {@link openEvmChannel}).
      *
      * 1. Approve token spend if needed
      * 2. Call TokenNetwork.openChannel()
      * 3. Extract channelId from ChannelOpened event
      * 4. Deposit initial funds if specified
      */
-    private openEvmChannel;
+    private openEvmChannelUnchecked;
     /**
      * Gets the current state of a payment channel from on-chain data.
      */
@@ -2742,406 +2799,6 @@ declare function applyDefaults(rawConfig: ToonClientConfig): ResolvedConfig;
  */
 declare function buildSettlementInfo(rawConfig: ToonClientConfig): ClientSettlementInfo | undefined;
 
-/**
- * Pet DVM Client-Side Types
- *
- * Locally defined types for pet DVM interaction utilities.
- * These mirror server-side types but do NOT import from @toon-protocol/pet-dvm,
- * @toon-protocol/pet-circuit, or @toon-protocol/memvid-node.
- *
- * @module pet/types
- */
-/** Plain-number stat values (all clamped to [1, 100]) */
-interface StatValues {
-    hunger: number;
-    happiness: number;
-    health: number;
-    hygiene: number;
-    energy: number;
-}
-/** Metadata for a pet DVM provider discovered via Kind 10035 events */
-interface PetDvmProvider {
-    /** ILP address of the provider's connector */
-    ilpAddress: string;
-    /** Per-interaction cost from skill.pricing['5900'] */
-    pricing: string;
-    /** Provider's Nostr pubkey (cryptographically bound from event.pubkey) */
-    pubkey: string;
-    /** Feature list from skill.features */
-    features: string[];
-}
-/** Parameters for building a Kind 5900 pet interaction request */
-interface PetInteractionRequestParams {
-    /** Blobbi identifier (non-empty string) */
-    blobbiId: string;
-    /** Action type (0-10, maps to Feed/Play/Clean/etc.) */
-    actionType: number;
-    /** Item identifier (>= 0) */
-    itemId: number;
-    /** Token cost for this interaction (>= 0) */
-    tokenCost: number;
-    /** Whether the pet is currently sleeping */
-    isSleeping: boolean;
-}
-/** Unsigned Nostr event structure compatible with nostr-tools finalizeEvent */
-interface UnsignedNostrEvent {
-    kind: number;
-    created_at: number;
-    tags: string[][];
-    content: string;
-}
-/** Parsed result data from Kind 6900 DVM response (base64 JSON in IlpSendResult.data) */
-interface PetInteractionResultData {
-    /** Current stat values */
-    stats: StatValues;
-    /** Current stage (0=Egg, 1=Baby, 2=Adult) */
-    stage: number;
-    /** Current evolution cycle (>= 0) */
-    cycle: number;
-    /** Unix timestamp of last interaction */
-    lastInteraction: number;
-    /** 64-char hex BLAKE3 hash of brain state */
-    brainHash: string;
-    /** Per-action-type cooldown timestamps */
-    cooldownTimestamps: number[];
-}
-/** Stat snapshot used in interaction result content */
-interface InteractionResultContent {
-    priorStats: StatValues;
-    decayedStats: StatValues;
-    finalStats: StatValues;
-    cycle: number;
-    stage: number;
-    tokenCost: number;
-}
-/** Proof status of a Kind 14919 event */
-type ProofStatus = 'optimistic' | 'proven';
-/** Parameters for building a Kind 30402 pet-for-sale classified listing */
-interface PetListingParams {
-    /** Blobbi identifier (non-empty string) — used as the 'd' tag */
-    blobbiId: string;
-    /** Asking price in USDC (> 0) */
-    askPriceUsdc: number;
-    /** 64-char hex lifecycleHash from on-chain PetZkApp state */
-    lifecycleHash: string;
-    /** Cumulative PET tokens spent (numeric string, >= "0") */
-    totalSpent: string;
-    /** Current stage: 0=Egg, 1=Baby, 2=Adult */
-    stage: number;
-    /** Current pet stats */
-    stats: StatValues;
-    /** Seller's Nostr pubkey (64-char hex) */
-    sellerPubkey: string;
-    /** Preferred relay URL for event relay routing */
-    relayUrl: string;
-    /** Listing expiry as unix timestamp */
-    expiresAt: number;
-}
-/** A parsed pet-for-sale listing (extends PetListingParams with event metadata) */
-interface PetListing extends PetListingParams {
-    /** Nostr event ID of the kind:30402 listing event */
-    eventId: string;
-    /** Unix timestamp when the listing event was created */
-    createdAt: number;
-}
-/** Filter options for filterPetListings() */
-interface PetListingFilterOptions {
-    /** Only include listings for pets at or above this stage */
-    minStage?: number;
-    /** Only include listings at or below this USDC price */
-    maxAskPriceUsdc?: number;
-    /** Only include listings where totalSpent >= this value (numeric string comparison) */
-    minTotalSpent?: string;
-    /** Only include listings from this seller pubkey */
-    sellerPubkey?: string;
-}
-/** Parameters for building a Kind 5900 pet purchase request (transfer-ownership) */
-interface PetPurchaseRequestParams {
-    /** Blobbi identifier being purchased */
-    blobbiId: string;
-    /** Nostr event ID of the kind:30402 listing being purchased */
-    listingEventId: string;
-    /** Buyer's Nostr pubkey (64-char hex) */
-    buyerPubkey: string;
-    /** Token cost for the purchase (>= 0) */
-    tokenCost: number;
-    /** Seller's Nostr pubkey — ILP payment routed to this pubkey (64-char hex) */
-    sellerPubkey: string;
-}
-/** Parsed data from a Kind 14919 pet interaction event */
-interface PetInteractionEventData {
-    /** Blobbi identifier from 'd' tag */
-    blobbiId: string;
-    /** Action type from 'action' tag */
-    actionType: number;
-    /** Item identifier from 'item' tag */
-    itemId: number;
-    /** Token cost from 'cost' tag */
-    tokenCost: number;
-    /** Evolution cycle from 'cycle' tag */
-    cycle: number;
-    /** Stage from 'stage' tag */
-    stage: number;
-    /** Brain hash from 'brain_hash' tag */
-    brainHash: string;
-    /** Proof status: 'optimistic' (no proof tag) or 'proven' (has proof + mina_tx tags) */
-    proofStatus: ProofStatus;
-    /** Parsed content JSON (stats before/after) */
-    content: InteractionResultContent | null;
-    /** Base64 proof data (only present when proven) */
-    proof?: string;
-    /** Mina transaction hash (only present when proven) */
-    minaTx?: string;
-}
-
-/**
- * Pet DVM Provider Discovery
- *
- * Filters Kind 10035 service discovery events to find providers that
- * support Pet DVM interactions (Kind 5900).
- *
- * @module pet/filterPetDvmProviders
- */
-
-/**
- * Minimal Nostr event shape needed for filtering.
- * Using a local interface to avoid importing nostr-tools types.
- */
-interface NostrEventLike$3 {
-    kind: number;
-    pubkey: string;
-    content: string;
-    tags: string[][];
-    id: string;
-    sig: string;
-    created_at: number;
-}
-/**
- * Filter Kind 10035 service discovery events to find pet DVM providers.
- *
- * Accepts raw NostrEvent[] and internally parses content via parseServiceDiscovery.
- * Filters events where skill.kinds includes 5900 (PET_INTERACTION_REQUEST_KIND).
- * Returns provider metadata sorted by price ascending (cheapest first).
- *
- * Handles missing/malformed skill descriptors gracefully (returns empty array, no throw).
- *
- * @param events - Array of raw Nostr events (kind:10035)
- * @returns Array of PetDvmProvider metadata, sorted by price ascending
- */
-declare function filterPetDvmProviders(events: NostrEventLike$3[]): PetDvmProvider[];
-
-/**
- * Pet Interaction Request Builder (Kind 5900)
- *
- * Builds unsigned Kind 5900 Nostr events for pet DVM interaction requests.
- * Compatible with nostr-tools/pure finalizeEvent for signing.
- *
- * @module pet/buildPetInteractionRequest
- */
-
-/**
- * Build an unsigned Kind 5900 pet interaction request event.
- *
- * All tag values are stringified per Nostr protocol convention.
- * The returned event is compatible with nostr-tools `finalizeEvent`.
- *
- * @param params - Typed interaction parameters
- * @returns Unsigned Nostr event ready for signing
- * @throws ValidationError for invalid input
- */
-declare function buildPetInteractionRequest(params: PetInteractionRequestParams): UnsignedNostrEvent;
-
-/**
- * Pet Interaction Result Parser (Kind 6900)
- *
- * Decodes base64-encoded JSON from IlpSendResult.data field.
- * Uses browser-safe atob() -- NOT Node.js Buffer -- for ditto React SPA compatibility.
- *
- * @module pet/parsePetInteractionResult
- */
-
-/**
- * Parse base64-encoded JSON result data from a Kind 6900 DVM response.
- *
- * Uses atob() for browser compatibility (ditto React SPA).
- * Returns null for malformed/missing data (no throw).
- *
- * Validates:
- * - brainHash is 64-char hex
- * - stats has all 5 fields
- * - cycle >= 0
- * - stage 0-2
- *
- * @param data - Base64-encoded JSON string from IlpSendResult.data
- * @returns Parsed PetInteractionResultData or null if invalid
- */
-declare function parsePetInteractionResult(data: string): PetInteractionResultData | null;
-
-/**
- * Pet Interaction Event Parser (Kind 14919)
- *
- * Parses Kind 14919 optimistic/proven pet interaction events.
- * Detects proof status from presence of 'proof' + 'mina_tx' tags.
- *
- * @module pet/parsePetInteractionEvent
- */
-
-/**
- * Minimal Nostr event shape needed for parsing.
- */
-interface NostrEventLike$2 {
-    kind: number;
-    pubkey: string;
-    content: string;
-    tags: string[][];
-    id: string;
-    sig: string;
-    created_at: number;
-}
-/**
- * Parse a Kind 14919 pet interaction event.
- *
- * Extracts all tag values and detects proof status:
- * - 'optimistic': no 'proof' tag
- * - 'proven': has 'proof' + 'mina_tx' tags
- *
- * Returns null if required tags are missing.
- *
- * @param event - A Nostr event (Kind 14919)
- * @returns Parsed PetInteractionEventData or null if malformed
- */
-declare function parsePetInteractionEvent(event: NostrEventLike$2): PetInteractionEventData | null;
-
-/**
- * Pet Listing Event Builder (Kind 30402)
- *
- * Builds unsigned Kind 30402 (NIP-99 classified listing) Nostr events
- * for pet-for-sale marketplace listings. Every listing includes a
- * verified biography attachment (lifecycleHash + totalSpent) so buyers
- * can verify the listing against on-chain PetZkApp state.
- *
- * Browser-compatible — no Node.js-only imports.
- *
- * @module pet/buildPetListingEvent
- */
-
-/**
- * Build an unsigned Kind 30402 pet-for-sale classified listing event.
- *
- * The listing uses the NIP-99 classified listing format with TOON-specific
- * extension tags for verified biography (lifecycleHash, totalSpent).
- * The `d` tag is set to `blobbiId` for stable parameterized replaceability —
- * republishing with the same `d` tag updates the listing on relays.
- *
- * The returned event is compatible with nostr-tools `finalizeEvent`.
- *
- * @param params - Typed listing parameters
- * @returns Unsigned Nostr event ready for signing and publishing
- */
-declare function buildPetListingEvent(params: PetListingParams): UnsignedNostrEvent;
-
-/**
- * Pet Listing Parser (Kind 30402)
- *
- * Parses Kind 30402 (NIP-99 classified listing) Nostr events into
- * typed PetListing objects. Returns null for invalid or malformed events.
- *
- * Browser-compatible — no Node.js-only imports.
- *
- * @module pet/parsePetListing
- */
-
-/** Minimal Nostr event shape required for parsing */
-interface NostrEventLike$1 {
-    id: string;
-    kind: number;
-    pubkey: string;
-    tags: string[][];
-    content: string;
-    created_at: number;
-}
-/**
- * Parse a Kind 30402 pet classified listing event into a PetListing.
- *
- * Validation rules:
- * - event.kind must be 30402
- * - 'd' tag must be present and non-empty
- * - 'price' tag must be present with a valid positive numeric first element
- * - 'lifecycle_hash' tag must be a 64-char hex string
- * - 'total_spent' tag must be a valid non-negative numeric string
- * - 'stage' tag must be present
- *
- * Stats are parsed from content JSON; unparseable content falls back to DEFAULT_STATS.
- *
- * @param event - A Nostr event (expected Kind 30402)
- * @returns Parsed PetListing or null if invalid
- */
-declare function parsePetListing(event: NostrEventLike$1): PetListing | null;
-
-/**
- * Pet Listing Discovery Filter
- *
- * Filters and sorts Kind 30402 pet marketplace listing events into
- * typed PetListing objects. Handles expiry, stage, price, biography
- * value, and seller filtering. Results sorted by totalSpent descending
- * (highest biography value first) to surface the most battle-hardened pets.
- *
- * Browser-compatible — no Node.js-only imports.
- *
- * @module pet/filterPetListings
- */
-
-/** Minimal Nostr event shape accepted by the filter */
-interface NostrEventLike {
-    id: string;
-    kind: number;
-    pubkey: string;
-    tags: string[][];
-    content: string;
-    created_at: number;
-}
-/**
- * Filter and sort Kind 30402 pet marketplace listing events.
- *
- * Parsing is done via parsePetListing — invalid events are silently dropped.
- * Expired listings (expiration tag < current unix time) are excluded.
- * Options allow additional filtering by stage, price, biography value, and seller.
- * Results are sorted by totalSpent descending (highest biography value first).
- *
- * @param events - Array of raw Nostr events to filter
- * @param options - Optional filter criteria
- * @returns Filtered and sorted array of PetListing objects
- */
-declare function filterPetListings(events: NostrEventLike[], options?: PetListingFilterOptions): PetListing[];
-
-/**
- * Pet Purchase Request Builder (Kind 5900, action type 9)
- *
- * Builds unsigned Kind 5900 Nostr events for pet transfer-ownership
- * purchase requests. Action type 9 is a reserved slot in the pet DVM
- * protocol — this event signals purchase intent and routes ILP payment
- * to the seller. The actual Mina on-chain ownership transfer (PetZkApp
- * .transferOperator) is handled by downstream stories.
- *
- * Browser-compatible — no Node.js-only imports.
- *
- * @module pet/buildPetPurchaseRequest
- */
-
-/**
- * Build an unsigned Kind 5900 pet purchase request event.
- *
- * Reuses the existing pet interaction event kind (5900) with action type 9
- * (transfer-ownership). The `listing` tag references the kind:30402 listing
- * event being purchased. The `p` tag routes ILP payment to the seller.
- *
- * The returned event is compatible with nostr-tools `finalizeEvent`.
- *
- * @param params - Typed purchase request parameters
- * @returns Unsigned Nostr event ready for signing and publishing
- */
-declare function buildPetPurchaseRequest(params: PetPurchaseRequestParams): UnsignedNostrEvent;
-
 /**
  * Devnet faucet helper.
  *
@@ -3551,4 +3208,4 @@ declare function loadKeystore(path: string, password: string): string;
  */
 declare function writeKeystoreFile(path: string, keystore: EncryptedKeystore): void;
 
-export { type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type ChainMetadata, type ChainSigner, ChannelManager, type ClaimMessage, type ClaimResolver, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type FaucetChain, type FundWalletOptions, type FundWalletResult, type H402FetchOptions, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpTransportChoice, type InteractionResultContent, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PetDvmProvider, type PetInteractionEventData, type PetInteractionRequestParams, type PetInteractionResultData, type PetListing, type PetListingFilterOptions, type PetListingParams, type PetPurchaseRequestParams, type ProofStatus, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type StatValues, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, type UnsignedNostrEvent, ValidationError, type VaultData, applyDefaults, applyNetworkPresets, buildBackupEvent, buildBackupFilter, buildPetInteractionRequest, buildPetListingEvent, buildPetPurchaseRequest, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, filterPetDvmProviders, filterPetListings, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isPrfSupported, loadKeystore, parseBackupPayload, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parsePetInteractionEvent, parsePetInteractionResult, parsePetListing, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readMinaDepositTotal, requestBlobStorage, selectIlpTransport, serializeHttpRequest, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };
+export { type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type ChainMetadata, type ChainSigner, ChannelFundingError, ChannelManager, type ClaimMessage, type ClaimResolver, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type FaucetChain, type FundWalletOptions, type FundWalletResult, type H402FetchOptions, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpTransportChoice, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, ValidationError, type VaultData, applyDefaults, applyNetworkPresets, buildBackupEvent, buildBackupFilter, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, extractArweaveTxId, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isInsufficientGasError, isPrfSupported, loadKeystore, parseBackupPayload, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readMinaDepositTotal, requestBlobStorage, selectIlpTransport, serializeHttpRequest, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };