Handle Hyperbalance conditional free-tier advisories

package.json

@@ -56,7 +56,7 @@
     "@inquirer/prompts": "^7.2.0",
     "@oclif/core": "^4.0.30",
     "@permaweb/aoconnect": "^0.0.85",
-    "@permaweb/hyperbalance": "^0.1.0",
+    "@permaweb/hyperbalance": "^0.2.0",
     "@permaweb/references": "^0.1.0",
     "arweave": "^1.15.7",
     "mime-types": "^3.0.1",

src/utils/__tests__/hyperbeam-uploader.test.ts

@@ -3,6 +3,8 @@ import { describe, expect, it } from 'vitest'
 import {
   hyperbeamAoFundingHint,
   hyperbeamBundlerLink,
+  hyperbeamFreeTierExhaustedMessage,
+  isConditionalFreeTierQuote,
   parseHyperbeamFundAmount,
 } from '../hyperbeam-uploader.js'
 
@@ -63,3 +65,44 @@ describe('parseHyperbeamFundAmount', () => {
     }
   })
 })
+
+describe('isConditionalFreeTierQuote', () => {
+  it('detects zero quotes that are conditional on free-tier quota', () => {
+    expect(
+      isConditionalFreeTierQuote({
+        advisories: [
+          {
+            code: 'conditional-free-tier',
+            message: 'Quota-dependent free quote',
+            severity: 'warning',
+          },
+        ],
+        amount: 0n,
+      }),
+    ).toBe(true)
+  })
+
+  it('does not treat paid quotes as conditional free-tier quotes', () => {
+    expect(
+      isConditionalFreeTierQuote({
+        advisories: [
+          {
+            code: 'conditional-free-tier',
+            message: 'Quota-dependent free quote',
+            severity: 'warning',
+          },
+        ],
+        amount: 1n,
+      }),
+    ).toBe(false)
+  })
+})
+
+describe('hyperbeamFreeTierExhaustedMessage', () => {
+  it('explains that trundler exhaustion becomes paid fallback', () => {
+    expect(hyperbeamFreeTierExhaustedMessage('Insufficient funds')).toContain(
+      'free-tier quota was exhausted',
+    )
+    expect(hyperbeamFreeTierExhaustedMessage()).toContain('AO payment')
+  })
+})

src/utils/hyperbeam-uploader.ts

@@ -13,6 +13,7 @@ import {
   type HyperbalanceProfile,
   HYPERBEAM_DEFAULT_LEDGER_ID,
   HYPERBEAM_DEFAULT_LEDGER_ROUTE,
+  type Quote,
   waitForAoAssignmentSlot,
 } from '@permaweb/hyperbalance'
 
@@ -290,7 +291,7 @@ export async function autoFundQuotedHyperbeamLedger(
 
 export async function quoteHyperbeamUpload(
   options: { signedBytes: number } & HyperbeamBundlerQuoteOptions,
-): Promise<{ amount: bigint; ledgerId?: string; tokenId?: string }> {
+): Promise<{ amount: bigint; conditionalFreeTier?: boolean; ledgerId?: string; tokenId?: string }> {
   const profile = await discoverHyperbeamAoBundlerProfile({
     ledgerId: options.ledgerId,
     nodeUrl: options.uploader,
@@ -302,7 +303,12 @@ export async function quoteHyperbeamUpload(
     profile,
   })
 
-  return { amount: quote.amount, ledgerId: quote.ledgerId, tokenId: quote.tokenId }
+  return {
+    amount: quote.amount,
+    conditionalFreeTier: isConditionalFreeTierQuote(quote),
+    ledgerId: quote.ledgerId,
+    tokenId: quote.tokenId,
+  }
 }
 
 export function hyperbeamBundlerLink(uploader: string, id: string, isManifest = false): string {
@@ -411,6 +417,30 @@ function autoFundUnavailableMessage(message: string): string {
   ].join('\n')
 }
 
+export function isConditionalFreeTierQuote(quote: Pick<Quote, 'advisories' | 'amount'>): boolean {
+  return (
+    quote.amount === 0n &&
+    (quote.advisories?.some((advisory) => advisory.code === 'conditional-free-tier') ?? false)
+  )
+}
+
+export function hyperbeamFreeTierExhaustedMessage(preview?: string): string {
+  const suffix = preview ? `: ${preview}` : ''
+  return [
+    `HyperBEAM bundler free-tier quota was exhausted during upload settlement${suffix}`,
+    'The node is now requiring AO payment. Direct quote calls do not reserve free-tier quota, so retry after funding the local ledger.',
+  ].join('\n\n')
+}
+
+function uploadErrorPreview(message: string, status: number): string | undefined {
+  const marker = `HTTP ${status}`
+  const start = message.indexOf(marker)
+  if (start < 0) return undefined
+
+  const suffix = message.slice(start + marker.length).trim()
+  return suffix.startsWith(':') ? suffix.slice(1).trim() || undefined : undefined
+}
+
 export class HyperbeamBundlerClient implements UploadClient {
   private readonly autoFund?: HyperbeamBundlerAutoFundOptions
   private readonly quote: HyperbeamBundlerQuoteOptions
@@ -446,13 +476,17 @@ export class HyperbeamBundlerClient implements UploadClient {
     const localId = item.id || toBase64Url(new DataItem(raw).id)
     const size: UploadSize = { payloadBytes: data.length, signedBytes: raw.length }
     let autoFundUnavailable: string | undefined
-    let autoFundQuote: { amount: bigint; ledgerId?: string; tokenId?: string } | undefined
+    let autoFundQuote:
+      | { amount: bigint; conditionalFreeTier?: boolean; ledgerId?: string; tokenId?: string }
+      | undefined
     let cost: UploadCost | undefined
+    let conditionalFreeTierQuote = false
 
     if (this.autoFund) {
       try {
         autoFundQuote = await quoteHyperbeamUpload({ ...this.quote, signedBytes: raw.length })
         cost = { amount: autoFundQuote.amount, token: 'AO' }
+        conditionalFreeTierQuote = autoFundQuote.conditionalFreeTier ?? false
       } catch (error) {
         autoFundUnavailable = cleanAutoFundErrorMessage(
           error instanceof Error ? error.message : String(error),
@@ -462,6 +496,7 @@ export class HyperbeamBundlerClient implements UploadClient {
       try {
         const quote = await quoteHyperbeamUpload({ ...this.quote, signedBytes: raw.length })
         cost = { amount: quote.amount, token: 'AO' }
+        conditionalFreeTierQuote = quote.conditionalFreeTier ?? false
       } catch {
         cost = undefined
       }
@@ -503,11 +538,15 @@ export class HyperbeamBundlerClient implements UploadClient {
       const message = error instanceof Error ? error.message : String(error)
       const needsPayment = message.includes('HTTP 402')
       const paymentHint = needsPayment
-        ? await this.paymentHint(autoFundUnavailable ? false : undefined)
+        ? await this.paymentHint(this.autoFund || autoFundUnavailable ? false : undefined)
         : undefined
+      const uploadMessage =
+        needsPayment && conditionalFreeTierQuote
+          ? hyperbeamFreeTierExhaustedMessage(uploadErrorPreview(message, 402))
+          : message
       throw new Error(
         [
-          message,
+          uploadMessage,
           needsPayment && autoFundUnavailable
             ? autoFundUnavailableMessage(autoFundUnavailable)
             : undefined,