@bounded-sh/client 0.0.114 → 0.0.115

package/dist/venue-escrow.d.ts

@@ -0,0 +1,113 @@
+/** The terms the funder signs. Amounts are USDC base units; `expiresAt` is a unix second. */
+export interface VenueEscrowTerms {
+    payee: string;
+    amountUsdc: number;
+    challengeSeconds: number;
+    expiresAt: number;
+    ref: string;
+}
+export interface VenueEscrowFunded {
+    escrowId: string;
+    rootAppId: string;
+    venueAppId: string;
+    /** The funding transaction, when the lane reports one (a poofnet commit can come back without). */
+    transactionId: string | null;
+}
+export interface VenueEscrowDisputed {
+    disputeId: string;
+    rootAppId: string;
+    venueAppId: string;
+    transactionId: string | null;
+}
+export type VenueEscrowState = 'failed' | 'pending' | 'released' | 'refunded' | 'disputed' | 'approved' | 'funded';
+/** One escrow as the public read reports it (mirrors `projectAgentEscrow` in bounded-platform's agent-escrow-public-routes.ts). */
+export interface VenueEscrow {
+    schemaVersion: string | null;
+    rootAppId: string;
+    escrowId: string;
+    funder: string | null;
+    payee: string | null;
+    amountUsdc: number | null;
+    challengeSeconds: number | null;
+    expiresAt: number | null;
+    ref: string | null;
+    at: number | null;
+    approvedAt: number | null;
+    approvedKind: string | null;
+    disputedAt: number | null;
+    disputedBy: string | null;
+    settledAt: number | null;
+    settledKind: string | null;
+    settledBy: string | null;
+    state: VenueEscrowState;
+}
+/**
+ * Why a call failed. `pending` means the outcome is not known yet: call `fundVenueEscrow` again
+ * with the SAME terms to settle it, never with new ones. `funded_other_terms` means an earlier,
+ * interrupted funding with different terms landed (see `escrowId`). Every other code is final for
+ * that attempt, and the next call starts fresh.
+ *
+ * - Before anything is sent: `invalid_input`, `sign_in_required`, `wallet_required`, `wallet_changed`,
+ *   `popup_blocked`, `storage_unavailable`, `lock_unavailable`, `in_progress`.
+ * - The grant mint (Bounded Auth, passed through): `invalid_request`, `invalid_token`, `origin_not_allowed`,
+ *   `not_an_openapps_app`, `agent_wallet_refused`, `rate_limited`, `venue_grant_unavailable`, plus
+ *   `venue_grant_refused` for any other refusal.
+ * - The venue write: `grant_rejected`, `rule_refused` (the venue's own rule, in its words; also an
+ *   approval slower than the two minutes a write stays valid), `sponsorship_refused`,
+ *   `sponsorship_unavailable`, `insufficient_balance`, `chain_mismatch` (the app configured another
+ *   chain than the venue's), `chain_not_configured` (no RPC could be resolved for the venue's chain;
+ *   not expected with the SDK's defaults), `top_level_required`, `declined` (the wallet or its window
+ *   said no), `write_failed`.
+ * - Settling a funding: `not_applied` (it never landed; nothing moved), `failed` (the venue's hook
+ *   failed; nothing moved), `taken` (another record holds the id), `pending`, `funded_other_terms`
+ *   (an interrupted funding with different terms landed; see `escrowId`).
+ * - Reading: `read_unavailable`.
+ */
+export type VenueEscrowErrorCode = 'invalid_input' | 'sign_in_required' | 'wallet_required' | 'wallet_changed' | 'popup_blocked' | 'storage_unavailable' | 'lock_unavailable' | 'in_progress' | 'invalid_request' | 'invalid_token' | 'origin_not_allowed' | 'not_an_openapps_app' | 'agent_wallet_refused' | 'rate_limited' | 'venue_grant_unavailable' | 'venue_grant_refused' | 'grant_rejected' | 'rule_refused' | 'sponsorship_refused' | 'sponsorship_unavailable' | 'insufficient_balance' | 'chain_mismatch' | 'chain_not_configured' | 'top_level_required' | 'declined' | 'write_failed' | 'not_applied' | 'failed' | 'taken' | 'pending' | 'funded_other_terms' | 'read_unavailable';
+/** Thrown by every venue escrow call. Branch on `code`; `error.name === 'VenueEscrowError'` also holds across bundled SDK copies. */
+export declare class VenueEscrowError extends Error {
+    readonly code: VenueEscrowErrorCode;
+    /** The escrow this concerns, when one exists: a pending, failed, taken or conflicting funding. */
+    readonly escrowId?: string;
+    constructor(code: VenueEscrowErrorCode, message: string, details?: {
+        escrowId?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Read one venue escrow from the public record: its terms and its state (`pending` until the
+ * venue's hook completes, `failed` when it did not). Resolves null when no such escrow exists.
+ * No sign-in is needed.
+ */
+export declare function getVenueEscrow(input: {
+    rootAppId: string;
+    escrowId: string;
+}): Promise<VenueEscrow | null>;
+/**
+ * Lock USDC in the venue escrow for `terms.payee`, signed by the wallet signed in here.
+ * MUST be called from a user click: an email (Turnkey) wallet's approval opens in its own Bounded
+ * window, which a browser only allows inside the click (it is opened here, before anything is
+ * awaited), and the approval shows the decoded terms. A Phantom or Wallet Standard wallet keeps
+ * its own prompt. On a real-chain venue the transaction is broadcast on the VENUE's chain: through
+ * the app's own `rpcUrl` when the app configured that same `chain` too (an `rpcUrl` alone does not
+ * say which chain it speaks), otherwise through the platform's default RPC for the venue's chain, so
+ * an app that never configured a chain just works. An app that configured a different `chain` is
+ * refused (`chain_mismatch`) before anything is signed.
+ *
+ * Funding is made safe to retry: a funding that was interrupted (page closed, answer lost) is
+ * saved before anything is sent, and the next call checks it instead of funding again, so pass
+ * the same terms and it resolves to the same `escrowId`. Store `escrowId` on your own record.
+ * See {@link VenueEscrowErrorCode} for the failures, and `pending` in particular.
+ */
+export declare function fundVenueEscrow(terms: VenueEscrowTerms): Promise<VenueEscrowFunded>;
+/**
+ * Dispute a funded venue escrow as its funder (or payee), signed by the wallet signed in here.
+ * MUST be called from a user click, for the same reason as {@link fundVenueEscrow}. `reason` is
+ * 1 to 400 bytes of UTF-8: the venue allows 1000 characters, but a longer reason does not fit one
+ * legacy-format transaction. Nothing is saved: a dispute that already landed makes the venue refuse
+ * a second one (`rule_refused`).
+ */
+export declare function disputeVenueEscrow(input: {
+    escrowId: string;
+    reason: string;
+}): Promise<VenueEscrowDisputed>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bounded-sh/client",
-    "version": "0.0.114",
+    "version": "0.0.115",
     "description": "Web and React Native client SDK for Bounded, the full-stack app builder and runtime for AI-built apps: hosted auth, policy-enforced data, files and search, functions, realtime subscriptions, and atomic writes.",
     "homepage": "https://bounded.sh/docs/sdk",
     "main": "./dist/index.js",
@@ -115,7 +115,7 @@
         "vite": "7.3.5"
     },
     "dependencies": {
-        "@bounded-sh/core": "0.0.114",
+        "@bounded-sh/core": "0.0.115",
         "@coral-xyz/anchor": "0.31.1",
         "@noble/curves": "^1.9.7",
         "@solana/kit": "8.2.0",