@bounded-sh/core 0.0.114 → 0.0.116

package/dist/client/operations.d.ts

@@ -30,6 +30,20 @@ export type RequestOverrides = {
      * deterministically; production builds a `Connection` from `config.rpcUrl`.
      */
     _solanaRpc?: SolanaWriteRpc;
+    /**
+     * @internal The venue grant write lane (venue-grant-write.ts). A single-use grant, not the
+     * caller's session, authenticates the write, so `setMany` also lets the lane refuse the
+     * execution lane a 202 reports, takes the poofnet commit's credential from the lane, and
+     * skips the post-confirm mirror read a grant cannot authorize. App code never sets it.
+     */
+    _grantLane?: GrantLane;
+};
+/** @internal See {@link RequestOverrides._grantLane}. */
+export type GrantLane = {
+    /** Throws to refuse `chain`, the execution lane the 202 reported, before anything is signed. */
+    assertLane(chain: string): void;
+    /** The credential for the poofnet `PUT items/signed` commit. A grant is single use, so each call mints a fresh one. */
+    commitHeaders(): Promise<Record<string, string>>;
 };
 export type SetOptions = {
     shouldSubmitTx?: boolean;

package/dist/client/reconcile.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Reconciliation for a `submitted` write receipt.
+ *
+ * A returned object cannot transition itself, and calling `set` again builds a
+ * FRESH transaction — which is exactly what must not happen while the first
+ * signature may still land. Without this call the `submitted` state is a dead
+ * end and its terminal exits are unreachable.
+ *
+ * Everything here polls the SAME signature. Nothing here ever builds a new
+ * transaction or broadcasts anything.
+ */
+import type { ClientConfig } from './config';
 import type { RequestOverrides } from './operations';
 import type { SetResult } from '../types';
 export type ReconcileSetResultOptions = {
@@ -18,6 +30,12 @@ export type WaitForSetResultOptions = ReconcileSetResultOptions & {
     /** Cancels the wait. The latest `submitted` receipt is returned, never discarded. */
     signal?: AbortSignal;
 };
+/**
+ * The Solana execution lane a client config REQUIRES, or `null` when the config
+ * carries no constraint. Only a positive contradiction rejects a receipt — an
+ * unmapped or unset `chain` is not evidence of a mismatch.
+ */
+export declare function requiredSolanaChain(config: ClientConfig): string | null;
 /**
  * Poll the SAME signature a `submitted` receipt carries and return the
  * resulting `SetResult`.

package/dist/client/venue-grant-write.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The venue grant write lane: create ONE document in another app (an OpenApps venue) as the
+ * wallet signed in here, authorized by a single-use grant instead of a venue session
+ * (VENUE-GRANT-DESIGN.md). The grant only lets the venue build that one transaction for that
+ * wallet; the wallet's own signature, checked by the venue's own rule, is the authority.
+ *
+ * The grant itself is minted by Bounded Auth at `POST {humanAuthApiUrl}/app-token/venue-grant`
+ * (contract: packages/cdk/cloudflare/shared/venue-grant.ts, which this package cannot import
+ * because the SDK packages publish separately). This module only spends one.
+ *
+ * It reuses `setMany`'s request and 202 handling through `_overrides`: the `_config` snapshot is
+ * this app's own config re-pointed at the VENUE app id, so the pre-sign validator (OA-0001) binds
+ * the venue app id and the full expected intent, and the signer stays this app's own AuthProvider
+ * (a Turnkey session or a Wallet Standard wallet). Nothing here is reachable from `createClient()`,
+ * which stays read-only.
+ *
+ * The chain a write runs on is the VENUE's, stated by its 202, never the app's: the app's own
+ * `chain` can only agree with it or be refused, and the transaction is broadcast through the app's
+ * `rpcUrl` only when the app configured that same chain, otherwise through `resolveRpcUrl(chain)`.
+ */
+import { type ClientConfig } from './config';
+import { type SetOptions } from './operations';
+import type { SetResult, SolanaWriteRpc } from '../types';
+export interface VenueGrantWriteOptions {
+    /** The venue app the grant was minted for. The write and its 202 validation bind THIS app id, never the caller's own. */
+    venueAppId: string;
+    /** The single-use grant that authorizes this one create. */
+    grant: string;
+    /**
+     * Mints a fresh grant for the same kind and id. The `PUT items` that built the approval spent the
+     * first, so the poofnet `PUT items/signed` commit needs its own. Called only on poofnet, after the
+     * wallet has signed.
+     */
+    commitGrant: () => Promise<string>;
+    /** As `set`'s `onBroadcast`: persist the signed transaction's receipt before it is broadcast (Solana lanes). */
+    onBroadcast?: SetOptions['onBroadcast'];
+    /**
+     * The RPC for a Solana lane the app did not configure itself: given the chain the venue's 202
+     * reported (`solana_devnet` or `solana_mainnet`), its RPC url, or null for none. The client SDK
+     * passes its platform default. See {@link resolveVenueRpcUrl} for how it ranks against the app's own.
+     */
+    resolveRpcUrl?: (chain: string) => string | null | undefined;
+    /** @internal Test seam, as `RequestOverrides._solanaRpc`. */
+    _solanaRpc?: SolanaWriteRpc;
+}
+/**
+ * The RPC a venue write on Solana lane `chain` is broadcast through, and a saved receipt of it is
+ * reconciled through. The app's own `rpcUrl` counts only when the app also configured this chain
+ * (an `rpcUrl` alone does not say which chain it speaks); otherwise `resolveRpcUrl(chain)`. Null
+ * when neither yields one.
+ *
+ * @internal Shared by the lane and by the client SDK's reconciliation of a saved receipt.
+ */
+export declare function resolveVenueRpcUrl(config: ClientConfig, chain: string, resolveRpcUrl?: (chain: string) => string | null | undefined): string | null;
+/**
+ * Write `document` at `path` in the venue `venueAppId` with a single-use grant. Resolves to the
+ * same discriminated {@link SetResult} as `set`, and throws exactly as `set` does, so the same
+ * `isWriteNotApplied` reading applies.
+ *
+ * @internal Used by `fundVenueEscrow` and `disputeVenueEscrow` in @bounded-sh/client. Not a stable API.
+ */
+export declare function setWithVenueGrant(path: string, document: Record<string, unknown>, options: VenueGrantWriteOptions): Promise<SetResult>;

package/dist/client/write-outcome.d.ts

@@ -14,6 +14,7 @@
  *   `onBroadcast` hook refusing). Nothing was sent.
  * - `broadcast_rejected`: the RPC definitively refused the signed bytes
  *   (preflight simulation, invalid transaction). They never entered the network.
+ *   On poofnet, the realtime worker answering the signed commit with a 4xx.
  * - `failed_onchain`: the transaction landed and failed, so the write reverted.
  *
  * The tag is plain data on the thrown object (`writeOutcome` + `writePhase`),