@blockrun/llm 3.14.3 → 3.15.0

package/dist/index.d.cts

@@ -1855,7 +1855,7 @@ declare class VideoClient {
      * Submits an async job, then polls until the video is ready. Typical total
      * wall-time is 60-180s, but upstream status can lag several minutes behind
      * actual completion. If upstream runs past the budget (default 15min),
-     * throws without charging — the job stays claimable ~48h via poll_url.
+     * throws with the existing poll URL; check billing before submitting again.
      *
      * @param prompt - Text description of the video
      * @param options - Optional generation parameters
@@ -2657,6 +2657,71 @@ declare class SolanaLLMClient {
     smartChat(prompt: string, options?: SmartChatOptions): Promise<SmartChatResponse>;
     /** Smart full message/tool completion paid on Solana. */
     smartChatCompletion(messages: ChatMessage[], options?: SmartChatCompletionOptions): Promise<SmartChatCompletionResponse>;
+    /**
+     * Stream a Server-Sent Events endpoint, paid on Solana.
+     *
+     * The Solana counterpart to `BlockrunClient.stream`, and the reason it had to
+     * exist: a streaming harness cannot use this client at all without it, so
+     * "BlockRun supports Solana" stopped being true the moment a caller streamed.
+     * `chatCompletion` buffers the whole answer, which is the wrong shape for an
+     * agent loop and for anything that shows tokens as they arrive.
+     *
+     * The handshake is the one the non-streaming paths use — `402`, sign an SPL
+     * TransferChecked authorization locally, replay with `PAYMENT-SIGNATURE` —
+     * with the same verification-phase re-sign on a stale blockhash. What differs
+     * is that the paid response is not read as JSON: it is handed to the SSE
+     * reader with its body untouched.
+     *
+     * A `200` on the first request is returned as-is and settles nothing. That is
+     * the free tier (the gateway answers a `billing_mode: "free"` model without a
+     * 402 at all) and it is also API-key mode, where billing is on the account
+     * rather than on a wallet.
+     *
+     * Yields each `data:` frame parsed as JSON, and stops at `data: [DONE]`.
+     * Malformed frames are skipped rather than thrown — see {@link readSseFrames}.
+     *
+     * @example
+     * for await (const chunk of client.stream<ChatChunk>("/v1/chat/completions", {
+     *   model: "deepseek/deepseek-chat",
+     *   messages: [{ role: "user", content: "Hi" }],
+     *   stream: true,
+     * })) {
+     *   process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
+     * }
+     *
+     * @param path - endpoint after the API root; a leading `/api` is tolerated.
+     * @param body - JSON request body. Set `stream: true` yourself — this method
+     *   does not inject it, because the gateway prices a streaming and a
+     *   non-streaming request the same and silently rewriting a caller's body is
+     *   how you end up debugging a request you did not send.
+     * @returns each decoded SSE frame, in order.
+     */
+    stream<T = unknown>(path: string, body?: Record<string, unknown>): AsyncGenerator<T, void, undefined>;
+    /**
+     * Get to a streaming response, paying for it if the gateway asks.
+     *
+     * Separate from {@link SolanaLLMClient.stream} because a generator cannot
+     * retry cleanly around a `yield`: the stale-blockhash re-sign has to finish
+     * before the first frame is handed out, and putting the loop here keeps the
+     * payment decision entirely ahead of any output the caller has seen.
+     *
+     * @param url - resolved endpoint URL.
+     * @param requestBody - the serialized body, reused verbatim on the paid retry
+     *   so the gateway prices and answers the same request it quoted for.
+     * @returns a response whose body has not been read.
+     */
+    private openPaidStream;
+    /**
+     * Resolve an endpoint path against this client's API root.
+     *
+     * A leading `/api` is stripped for the same reason `BlockrunClient` strips
+     * it: the documented paths are written `/api/v1/…` on the website and
+     * `/v1/…` in this SDK, and a caller who copies one into the other should get
+     * their request rather than a 404.
+     * @param path - endpoint path, with or without a leading slash.
+     * @returns the absolute URL to call.
+     */
+    private buildUrl;
     /** List available models. */
     listModels(): Promise<Model[]>;
     /**
@@ -2777,11 +2842,46 @@ declare class SolanaLLMClient {
     /** True if using sol.blockrun.ai. */
     isSolana(): boolean;
     private requestWithPayment;
+    /**
+     * Turn a `402` into a signed Solana payment payload.
+     *
+     * Extracted because four call sites need it — chat, the raw POST helpers, the
+     * raw GET helper, and {@link SolanaLLMClient.stream} — and it had been
+     * written out three times before this. That mattered more than ordinary
+     * duplication: this is the code that signs a transfer of the caller's USDC,
+     * so three copies meant every fix to it had to be applied three times or
+     * quietly apply to two thirds of the paths.
+     *
+     * @param url - the request being paid for.
+     * @param response - the gateway's `402`, not yet consumed.
+     * @param forceFreshBlockhash - set on a re-sign after a stale-blockhash
+     *   rejection, so the retry cannot produce byte-identical transaction bytes.
+     * @param resourceFallback - resource URL to claim when the 402 states none.
+     * @returns the header value to replay with, and what it will settle for.
+     * @throws PaymentError when the 402 carries no usable Solana requirements.
+     */
+    private signPaymentFrom402;
     private handlePaymentAndRetry;
     private requestWithPaymentRaw;
     private handlePaymentAndRetryRaw;
     private getWithPaymentRaw;
     private handleGetPaymentAndRetryRaw;
+    /**
+     * Fail a post-payment response, telling a re-signable rejection from a real one.
+     *
+     * A `402` here is not "pay again": it is the gateway refusing the payment we
+     * just signed. Only a rejection the gateway attributes to the VERIFICATION
+     * phase is safe to re-sign — anything settled, or ambiguous about which
+     * phase it failed in, could already have moved USDC, and re-signing it would
+     * pay twice. {@link isSafeStaleBlockhashResponse} is where that judgement
+     * lives.
+     * @param response - the reply to the paid request.
+     * @throws SafeStaleBlockhashError when the caller should re-sign, PaymentError
+     *   when it should not, APIError for any other failure.
+     */
+    private assertPaid;
+    /** Count one settled x402 payment against the session total. */
+    private recordSettlement;
     private fetchWithTimeout;
 }
 /**

package/dist/index.d.ts

@@ -1855,7 +1855,7 @@ declare class VideoClient {
      * Submits an async job, then polls until the video is ready. Typical total
      * wall-time is 60-180s, but upstream status can lag several minutes behind
      * actual completion. If upstream runs past the budget (default 15min),
-     * throws without charging — the job stays claimable ~48h via poll_url.
+     * throws with the existing poll URL; check billing before submitting again.
      *
      * @param prompt - Text description of the video
      * @param options - Optional generation parameters
@@ -2657,6 +2657,71 @@ declare class SolanaLLMClient {
     smartChat(prompt: string, options?: SmartChatOptions): Promise<SmartChatResponse>;
     /** Smart full message/tool completion paid on Solana. */
     smartChatCompletion(messages: ChatMessage[], options?: SmartChatCompletionOptions): Promise<SmartChatCompletionResponse>;
+    /**
+     * Stream a Server-Sent Events endpoint, paid on Solana.
+     *
+     * The Solana counterpart to `BlockrunClient.stream`, and the reason it had to
+     * exist: a streaming harness cannot use this client at all without it, so
+     * "BlockRun supports Solana" stopped being true the moment a caller streamed.
+     * `chatCompletion` buffers the whole answer, which is the wrong shape for an
+     * agent loop and for anything that shows tokens as they arrive.
+     *
+     * The handshake is the one the non-streaming paths use — `402`, sign an SPL
+     * TransferChecked authorization locally, replay with `PAYMENT-SIGNATURE` —
+     * with the same verification-phase re-sign on a stale blockhash. What differs
+     * is that the paid response is not read as JSON: it is handed to the SSE
+     * reader with its body untouched.
+     *
+     * A `200` on the first request is returned as-is and settles nothing. That is
+     * the free tier (the gateway answers a `billing_mode: "free"` model without a
+     * 402 at all) and it is also API-key mode, where billing is on the account
+     * rather than on a wallet.
+     *
+     * Yields each `data:` frame parsed as JSON, and stops at `data: [DONE]`.
+     * Malformed frames are skipped rather than thrown — see {@link readSseFrames}.
+     *
+     * @example
+     * for await (const chunk of client.stream<ChatChunk>("/v1/chat/completions", {
+     *   model: "deepseek/deepseek-chat",
+     *   messages: [{ role: "user", content: "Hi" }],
+     *   stream: true,
+     * })) {
+     *   process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
+     * }
+     *
+     * @param path - endpoint after the API root; a leading `/api` is tolerated.
+     * @param body - JSON request body. Set `stream: true` yourself — this method
+     *   does not inject it, because the gateway prices a streaming and a
+     *   non-streaming request the same and silently rewriting a caller's body is
+     *   how you end up debugging a request you did not send.
+     * @returns each decoded SSE frame, in order.
+     */
+    stream<T = unknown>(path: string, body?: Record<string, unknown>): AsyncGenerator<T, void, undefined>;
+    /**
+     * Get to a streaming response, paying for it if the gateway asks.
+     *
+     * Separate from {@link SolanaLLMClient.stream} because a generator cannot
+     * retry cleanly around a `yield`: the stale-blockhash re-sign has to finish
+     * before the first frame is handed out, and putting the loop here keeps the
+     * payment decision entirely ahead of any output the caller has seen.
+     *
+     * @param url - resolved endpoint URL.
+     * @param requestBody - the serialized body, reused verbatim on the paid retry
+     *   so the gateway prices and answers the same request it quoted for.
+     * @returns a response whose body has not been read.
+     */
+    private openPaidStream;
+    /**
+     * Resolve an endpoint path against this client's API root.
+     *
+     * A leading `/api` is stripped for the same reason `BlockrunClient` strips
+     * it: the documented paths are written `/api/v1/…` on the website and
+     * `/v1/…` in this SDK, and a caller who copies one into the other should get
+     * their request rather than a 404.
+     * @param path - endpoint path, with or without a leading slash.
+     * @returns the absolute URL to call.
+     */
+    private buildUrl;
     /** List available models. */
     listModels(): Promise<Model[]>;
     /**
@@ -2777,11 +2842,46 @@ declare class SolanaLLMClient {
     /** True if using sol.blockrun.ai. */
     isSolana(): boolean;
     private requestWithPayment;
+    /**
+     * Turn a `402` into a signed Solana payment payload.
+     *
+     * Extracted because four call sites need it — chat, the raw POST helpers, the
+     * raw GET helper, and {@link SolanaLLMClient.stream} — and it had been
+     * written out three times before this. That mattered more than ordinary
+     * duplication: this is the code that signs a transfer of the caller's USDC,
+     * so three copies meant every fix to it had to be applied three times or
+     * quietly apply to two thirds of the paths.
+     *
+     * @param url - the request being paid for.
+     * @param response - the gateway's `402`, not yet consumed.
+     * @param forceFreshBlockhash - set on a re-sign after a stale-blockhash
+     *   rejection, so the retry cannot produce byte-identical transaction bytes.
+     * @param resourceFallback - resource URL to claim when the 402 states none.
+     * @returns the header value to replay with, and what it will settle for.
+     * @throws PaymentError when the 402 carries no usable Solana requirements.
+     */
+    private signPaymentFrom402;
     private handlePaymentAndRetry;
     private requestWithPaymentRaw;
     private handlePaymentAndRetryRaw;
     private getWithPaymentRaw;
     private handleGetPaymentAndRetryRaw;
+    /**
+     * Fail a post-payment response, telling a re-signable rejection from a real one.
+     *
+     * A `402` here is not "pay again": it is the gateway refusing the payment we
+     * just signed. Only a rejection the gateway attributes to the VERIFICATION
+     * phase is safe to re-sign — anything settled, or ambiguous about which
+     * phase it failed in, could already have moved USDC, and re-signing it would
+     * pay twice. {@link isSafeStaleBlockhashResponse} is where that judgement
+     * lives.
+     * @param response - the reply to the paid request.
+     * @throws SafeStaleBlockhashError when the caller should re-sign, PaymentError
+     *   when it should not, APIError for any other failure.
+     */
+    private assertPaid;
+    /** Count one settled x402 payment against the session total. */
+    private recordSettlement;
     private fetchWithTimeout;
 }
 /**