import { type TransactionSigner } from '@solana/kit'; import { type SelectSolanaSessionChallengeOptions } from './ChallengeSelection.js'; import { ActiveSession, type AmountLike, type CommitReceipt, type MeteringDirective, type OpenPayload, type SessionChallenge, type SessionMode, type SignedVoucher } from './Session.js'; type FetchInput = Parameters[0]; type FetchInit = Parameters[1]; /** * Request tuple returned by request preparation hooks. */ export interface PreparedFetchRequest { /** Fetch init to use for the attempt. */ readonly init?: FetchInit; /** Fetch input (URL or `Request`) to use for the attempt. */ readonly input: FetchInput; } /** * Session details returned by an opener after local/on-chain setup succeeds. */ export interface SessionOpenResult { /** Open action that authorizes the paid retry. */ readonly payload: OpenPayload & { readonly action: 'open'; }; /** Local session that signs vouchers from here on. */ readonly session: ActiveSession; /** Optional client identifier serialized into the credential. */ readonly source?: string | undefined; } /** * Parameters passed to a session opener. */ export interface SessionOpenParameters { /** Parsed Solana session challenge from the 402. */ readonly challenge: SessionChallenge; /** Fetch init of the original attempt. */ readonly init?: FetchInit; /** Fetch input of the original attempt. */ readonly input: FetchInput; /** The raw 402 response. */ readonly response: Response; } /** * Opens a payment session and returns the action that should authorize the retry. */ export type SessionOpener = (parameters: SessionOpenParameters) => Promise | SessionOpenResult; /** * Hook for transforming requests before the first attempt and paid retry. */ export type PrepareSessionRequest = (request: PreparedFetchRequest) => PreparedFetchRequest; /** * State created after a 402 session challenge has been paid. */ export interface SessionFetchOpenState extends SessionOpenResult { /** Serialized `Authorization` header value used on retries and commits. */ readonly authorization: string; /** Challenge the session was opened against. */ readonly challenge: SessionChallenge; /** URL voucher commits are POSTed back to (the opened resource by default). */ readonly commitUrl: string; } /** * Parameters used to reserve a metered delivery. */ export interface ReserveSessionDeliveryParameters { /** Delivery price, in base units. */ readonly amount: string; /** Endpoint the eventual commit should be POSTed to. */ readonly commitUrl: string; /** Unique id for the delivery being reserved. */ readonly deliveryId: string; /** Session the delivery is billed against. */ readonly session: ActiveSession; } /** * Parameters used to commit a metered delivery. */ export interface CommitSessionDeliveryParameters { /** Committed amount, in base units. */ readonly amount: string; /** Serialized `Authorization` header value for the commit request. */ readonly authorization: string; /** Directive issued when the delivery was reserved. */ readonly directive: MeteringDirective; /** Session signing the commit voucher. */ readonly session: ActiveSession; /** Signed cumulative voucher covering the delivery. */ readonly voucher: SignedVoucher; } /** * Events emitted by `SessionFetchClient`. */ export type SessionFetchEvent = { readonly cumulativeAmount: string; readonly deltaAmount: string; readonly sessionId: string; readonly type: 'watermark'; } | { readonly challenge: SessionChallenge; readonly type: 'challenge'; } | { readonly open: SessionFetchOpenState; readonly type: 'open'; } | { readonly receipt: CommitReceipt; readonly type: 'commit'; } | { readonly response: Response; readonly type: 'retry'; }; /** * High-level HTTP helper for Solana payment sessions. * * It handles session 402 challenges, paid retries, delivery reservations, and * throttled cumulative voucher commits. Apps only need to open the session and * report their current metered cumulative amount while they stream work. */ export declare class SessionFetchClient { #private; constructor(parameters: SessionFetchClient.Parameters); /** * Drop-in replacement for `fetch`. */ readonly fetch: typeof globalThis.fetch; /** Last open session state, when available. */ get open(): SessionFetchOpenState | undefined; /** Active local session, when available. */ get session(): ActiveSession | undefined; /** Current accepted cumulative voucher amount. */ get cumulativeAmount(): string; /** Highest locally observed cumulative watermark. */ get targetCumulativeAmount(): string | undefined; /** * Fetches a resource, automatically opening a session when a Solana session * 402 challenge is returned. */ fetchWithSession(input: FetchInput, init?: FetchInit): Promise; /** * Records the latest absolute cumulative amount. The client emits the local * watermark immediately and sends a voucher commit at most once per interval. */ recordCumulative(cumulativeAmount: AmountLike, options?: SessionFetchClient.RecordOptions): void; /** * Commits an absolute cumulative amount immediately. */ commitCumulative(cumulativeAmount: AmountLike): Promise; /** * Sends the latest recorded cumulative watermark and waits for all pending * commits to settle. */ flush(): Promise; private prepare; /** * Installs a freshly opened session. When the channel changes, any pending * watermark is flushed against the previous channel first (best effort; * a failure latches as a recoverable commit failure) and the commit * watermark state is re-keyed to the new channel so no voucher can sign a * cumulative the new channel did not meter. */ private replaceOpenState; private queueCommit; private queueCommitFor; private scheduleTrailingCommit; private clearTrailingCommit; private commitTarget; private reserveDelivery; private commitDelivery; private requireOpen; private throwCommitFailure; private emit; } export declare namespace SessionFetchClient { interface Parameters { /** Underlying fetch. Defaults to `globalThis.fetch`. */ readonly fetch?: typeof globalThis.fetch | undefined; /** Minimum interval between live voucher commits, in ms. Defaults to 1000. */ readonly liveCommitIntervalMs?: number | undefined; /** Observer for challenge / open / watermark / commit / retry events. */ readonly onEvent?: ((event: SessionFetchEvent) => void) | undefined; /** Opens the session when a 402 challenge arrives (wallet approval, channel open). */ readonly opener: SessionOpener; /** Hook applied to the first attempt and the paid retry (e.g. header stripping). */ readonly prepareRequest?: PrepareSessionRequest | undefined; /** Currency / network filter for picking among multiple advertised challenges. */ readonly selectChallenge?: SelectSolanaSessionChallengeOptions | undefined; } interface RecordOptions { /** Delta reported in the watermark event. Defaults to target − current. */ readonly deltaAmount?: AmountLike | undefined; /** Commit immediately instead of waiting for the live-commit interval. */ readonly force?: boolean | undefined; } } /** * Creates a high-level Solana session fetch client. */ export declare function createSessionFetch(parameters: SessionFetchClient.Parameters): SessionFetchClient; /** * Creates a development-only opener that fabricates pull/push open proofs. * * This is useful for local gateways and demos. Production clients should pass an * opener that performs the real wallet approval or channel open transaction. * Delegated pull opens build real pre-signed multi-delegate transactions when a * `signer` and a recent blockhash are available; without them the opener * refuses to fabricate the delegation payloads. */ export declare function createEphemeralSessionOpener(options?: createEphemeralSessionOpener.Options): SessionOpener; export declare namespace createEphemeralSessionOpener { interface Options { /** Pull: delegated amount to approve, in base units. Defaults to the challenge cap. */ readonly approvedAmount?: AmountLike | undefined; /** Cumulative already authorized when resuming, in base units. Defaults to 0. */ readonly cumulative?: AmountLike | undefined; /** Pull: nonce for the delegation PDA derivation. Defaults to 0. */ readonly delegationNonce?: AmountLike | undefined; /** Push: channel deposit, in base units. Defaults to the challenge cap. */ readonly deposit?: AmountLike | undefined; /** Voucher expiry as a unix timestamp (seconds). */ readonly expiresAt?: AmountLike | undefined; /** Pull: pre-built multi-delegate init transaction (base64), overriding the built one. */ readonly initMultiDelegateTx?: string | undefined; /** Funding mode. Defaults to the first server-advertised mode. */ readonly mode?: SessionMode | undefined; /** Pull: wallet that owns the delegated token account (base58). Defaults to the signer. */ readonly owner?: string | undefined; /** Recent blockhash used to pre-sign delegation transactions. */ readonly recentBlockhash?: string | undefined; /** Open transaction signature. Defaults to a fabricated one (push) or a pending marker (pull). */ readonly signature?: string | undefined; /** User wallet used to pre-sign the multi-delegate transactions for delegated pull opens. */ readonly signer?: TransactionSigner | undefined; /** Optional client identifier serialized into credentials. */ readonly source?: string | undefined; /** Pull: delegated token account override (base58). */ readonly tokenAccount?: string | undefined; /** Push: base64 signed open transaction for server-side submission. */ readonly transaction?: string | undefined; /** Pull: pre-built delegation update transaction (base64), overriding the built one. */ readonly updateDelegationTx?: string | undefined; } } /** * Returns a request preparation hook that removes sensitive headers before * forwarding traffic through a payment gateway. */ export declare function stripRequestHeaders(names: readonly string[]): PrepareSessionRequest; /** * Temporarily patches `globalThis.fetch` while an SDK that does not accept a * fetch option performs its work. */ export declare function withPatchedGlobalFetch(patchedFetch: typeof globalThis.fetch, operation: () => Promise): Promise; export {}; //# sourceMappingURL=SessionFetch.d.ts.map