@meddleware/walrus-ui 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meddleware/walrus-ui",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Standalone Vue 3 SPA for uploading blobs to Walrus decentralised storage and managing owned blobs — wallet-connected, NFT-gated relay support.",
   "author": "MeddleWare <meddleware@proton.me>",
   "license": "0BSD",
@@ -20,7 +20,10 @@
     "dev": "vite",
     "build": "vue-tsc --noEmit && vite build",
     "preview": "vite preview",
-    "type-check": "vue-tsc --noEmit"
+    "type-check": "vue-tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test"
   },
   "publishConfig": {
     "access": "public"
@@ -37,10 +40,12 @@
     "vue": "^3.5.40"
   },
   "devDependencies": {
+    "@playwright/test": "~1.49.1",
     "@types/node": "~24.12.2",
     "@vitejs/plugin-vue": "^6.0.8",
     "typescript": "~6.0.0",
     "vite": "^8.1.5",
+    "vitest": "~2.1.9",
     "vue-tsc": "~3.3.0"
   },
   "engines": {

package/src/App.vue

@@ -11,7 +11,8 @@ import type { UploadResult } from '@meddleware/walrus-relay'
 // Lightweight URL import — just the wasm asset URL (does not pull the walrus client).
 import walrusWasmUrl from '@mysten/walrus-wasm/web/walrus_wasm_bg.wasm?url'
 import { useWallet, getSuiClient } from './wallet.js'
-import { NETWORK, OPERATOR_RELAY_HOSTS, relayHosts, accessGate } from './config.js'
+import { NETWORK, OPERATOR_RELAY_HOSTS, relayHosts, accessGate, uploadRelayMaxTipMist } from './config.js'
+import { runBlobUpload } from './upload-flow.js'
 import MyBlobs from './components/MyBlobs.vue'
 
 type Tab = 'upload' | 'blobs'
@@ -43,15 +44,15 @@ async function onPurchase(): Promise<void> {
   }
 }
 
-// Wire the shared WalrusUpload widget to @meddleware/walrus-client + the wallet.
+// Wire the shared WalrusUpload widget to the extracted upload orchestration + the wallet. The
+// register/upload/certify sequence lives in src/upload-flow.ts (unit-tested); this closure only
+// gathers the wallet-bound inputs (executor, sui client, gated proof token) and delegates.
 async function performUpload(
   bytes: Uint8Array,
   opts: { relayHost: string; onStatus: (s: string) => void },
 ): Promise<UploadResult> {
   if (!account.value) throw new Error('Connect your wallet first.')
-  const { createWalrusClient, createBlobUploadFlow, walrusBlobUrl } = await import('@meddleware/walrus-client')
   const executor = await buildExecutor(NETWORK)
-  const suiClient = getSuiClient(NETWORK)
 
   // If the relay is NFT-gated and we hold access, attach a signed proof token.
   let authToken: string | undefined
@@ -63,41 +64,19 @@ async function performUpload(
     })
   }
 
-  const client = createWalrusClient({
+  return runBlobUpload({
+    bytes,
     network: NETWORK,
+    relayHost: opts.relayHost,
+    address: account.value.address,
     wasmUrl: walrusWasmUrl,
-    uploadRelayHost: opts.relayHost,
-    uploadRelayAuthToken: authToken,
-    uploadRelayMaxTipMist: Number(import.meta.env.VITE_UPLOAD_RELAY_MAX_TIP_MIST) || 50_000_000,
-  })
-  const flow = createBlobUploadFlow(client, bytes)
-
-  opts.onStatus('Encoding…')
-  await flow.encode()
-
-  opts.onStatus('Registering blob (approve in wallet)…')
-  const regTx = flow.register({
-    owner: account.value.address,
+    maxTipMist: uploadRelayMaxTipMist(),
     epochs: MAX_SINGLE_RESERVATION_EPOCHS,
-    deletable: false,
+    executor,
+    suiClient: getSuiClient(NETWORK),
+    authToken,
+    onStatus: opts.onStatus,
   })
-  regTx.setSenderIfNotSet(account.value.address)
-  await regTx.build({ client: suiClient })
-  const reg = await executor.signAndExecute(regTx)
-  await executor.waitForTransaction(reg.digest)
-
-  opts.onStatus('Uploading to the relay…')
-  await flow.upload({ digest: reg.digest })
-
-  opts.onStatus('Certifying (approve in wallet)…')
-  const certTx = flow.certify()
-  certTx.setSenderIfNotSet(account.value.address)
-  await certTx.build({ client: suiClient })
-  const cert = await executor.signAndExecute(certTx)
-  await executor.waitForTransaction(cert.digest)
-
-  const blob = await flow.getBlob()
-  return { blobId: blob.blobId, url: walrusBlobUrl(NETWORK, blob.blobId), digest: cert.digest }
 }
 
 function onUploaded(r: UploadResult): void {

package/src/config.ts

@@ -8,7 +8,11 @@ import {
   accessGateNftType,
 } from '@meddleware/walrus-relay'
 
-const env = (import.meta as unknown as { env?: Record<string, string | undefined> }).env ?? {}
+/** Build-time env bag. Injectable on the env-reading helpers below purely so unit tests can exercise
+ *  each branch without depending on Vite's (frozen) `import.meta.env` inlining. */
+export type EnvSource = Record<string, string | undefined>
+
+const env: EnvSource = (import.meta as unknown as { env?: EnvSource }).env ?? {}
 
 /** Active Walrus network, from `VITE_NETWORK` (default `testnet`). */
 export const NETWORK: WalrusNetwork = (env.VITE_NETWORK as WalrusNetwork) || 'testnet'
@@ -30,6 +34,19 @@ export function relayHosts(network: WalrusNetwork): { operator: string; public:
   return { operator: OPERATOR_RELAY_HOSTS[network], public: PUBLIC_WALRUS_RELAY_HOSTS[network] }
 }
 
+/** Default relay tip ceiling (MIST) when `VITE_UPLOAD_RELAY_MAX_TIP_MIST` is unset (0.05 SUI). */
+export const DEFAULT_UPLOAD_RELAY_MAX_TIP_MIST = 50_000_000
+
+/**
+ * Cap on the relay tip payment in MIST, from `VITE_UPLOAD_RELAY_MAX_TIP_MIST`. This is a ceiling to
+ * prevent overpayment (the relay asks for the minimum), NOT a fixed charge. A non-positive or
+ * unparseable value falls back to {@link DEFAULT_UPLOAD_RELAY_MAX_TIP_MIST}.
+ */
+export function uploadRelayMaxTipMist(envSource: EnvSource = env): number {
+  const parsed = Number(envSource.VITE_UPLOAD_RELAY_MAX_TIP_MIST)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_UPLOAD_RELAY_MAX_TIP_MIST
+}
+
 /**
  * JSON-RPC endpoint used to build + execute the register/certify transactions.
  * NOTE: this is JSON-RPC (the public testnet fullnode serves gRPC only for JSON-RPC,
@@ -45,19 +62,19 @@ export const RPC_URLS: Record<WalrusNetwork, string> = {
  * packageId and platformConfigId are hardcoded in the library — operators only
  * need to supply their Gate object ID, soulbound flag, and purchase price.
  */
-export function accessGate(network: WalrusNetwork): RelayGateConfig | null {
+export function accessGate(network: WalrusNetwork, envSource: EnvSource = env): RelayGateConfig | null {
   const NET = network.toUpperCase()
   const packageId = ACCESS_GATE_PACKAGE_ID[network]
   const platformConfigId = ACCESS_GATE_PLATFORM_CONFIG_ID[network]
-  const gateId = env[`VITE_ACCESS_GATE_ID_${NET}`]
+  const gateId = envSource[`VITE_ACCESS_GATE_ID_${NET}`]
   if (!packageId || !platformConfigId || !gateId) return null
-  const soulbound = env[`VITE_ACCESS_GATE_SOULBOUND_${NET}`] === 'true'
+  const soulbound = envSource[`VITE_ACCESS_GATE_SOULBOUND_${NET}`] === 'true'
   return {
     packageId,
     gateId,
     platformConfigId,
     nftType: accessGateNftType(network, soulbound),
     soulbound,
-    priceMist: BigInt(env[`VITE_ACCESS_GATE_PRICE_MIST_${NET}`] || '0'),
+    priceMist: BigInt(envSource[`VITE_ACCESS_GATE_PRICE_MIST_${NET}`] || '0'),
   }
 }

package/src/upload-flow.ts

@@ -0,0 +1,100 @@
+// The multi-step Walrus blob upload orchestration (encode → register → upload → certify → resolve),
+// extracted from App.vue so it can be unit-tested and reused by the e2e harness.
+//
+// The `@mysten/walrus` wasm client must NOT be pulled into the eager module graph (see CLAUDE.md),
+// so this module never imports @meddleware/walrus-client at top level — it loads it lazily through
+// the injectable `loadWalrusClient` (default: a dynamic import). Tests inject a fake loader.
+import type { UploadResult } from '@meddleware/walrus-relay'
+
+/** Minimal transaction executor — the structural subset App.vue's wallet executor already provides. */
+export interface UploadExecutor {
+  signAndExecute(tx: unknown): Promise<{ digest: string }>
+  waitForTransaction(digest: string): Promise<unknown>
+}
+
+/** The slice of `@meddleware/walrus-client` this flow needs. */
+export interface WalrusClientModule {
+  createWalrusClient: (opts: Record<string, unknown>) => unknown
+  createBlobUploadFlow: (client: unknown, bytes: Uint8Array) => BlobUploadFlow
+  walrusBlobUrl: (network: string, blobId: string) => string
+}
+
+interface BuiltTx {
+  setSenderIfNotSet(address: string): void
+  build(opts: { client: unknown }): Promise<unknown>
+}
+
+interface BlobUploadFlow {
+  encode(): Promise<void>
+  register(opts: { owner: string; epochs: number; deletable: boolean }): BuiltTx
+  upload(opts: { digest: string }): Promise<void>
+  certify(): BuiltTx
+  getBlob(): Promise<{ blobId: string }>
+}
+
+export interface RunBlobUploadDeps {
+  bytes: Uint8Array
+  network: string
+  relayHost: string
+  /** Owner/sender address (already-connected wallet account). */
+  address: string
+  /** Wasm bundle URL for the Walrus client. */
+  wasmUrl: string
+  /** Cap on the relay tip payment in MIST. */
+  maxTipMist: number
+  /** Blob storage reservation length in epochs. */
+  epochs: number
+  executor: UploadExecutor
+  /** A Sui client used to `build()` the register/certify transactions. */
+  suiClient: unknown
+  /** Optional Bearer proof token for an NFT-gated relay. */
+  authToken?: string
+  onStatus: (s: string) => void
+  /** Lazy loader for the Walrus client module (keeps wasm out of the eager bundle). */
+  loadWalrusClient?: () => Promise<WalrusClientModule>
+}
+
+/**
+ * Register → upload → certify a blob and resolve its id + public URL. Two wallet approvals
+ * (register, certify) are requested via `executor`; `onStatus` narrates each step.
+ */
+export async function runBlobUpload(deps: RunBlobUploadDeps): Promise<UploadResult> {
+  // The real module's flow types are richer than the narrow structural subset we use here, so the
+  // default loader casts through `unknown`. Tests inject an exact-shape fake instead.
+  const load =
+    deps.loadWalrusClient ??
+    (async () => (await import('@meddleware/walrus-client')) as unknown as WalrusClientModule)
+  const { createWalrusClient, createBlobUploadFlow, walrusBlobUrl } = await load()
+
+  const client = createWalrusClient({
+    network: deps.network,
+    wasmUrl: deps.wasmUrl,
+    uploadRelayHost: deps.relayHost,
+    uploadRelayAuthToken: deps.authToken,
+    uploadRelayMaxTipMist: deps.maxTipMist,
+  })
+  const flow = createBlobUploadFlow(client, deps.bytes)
+
+  deps.onStatus('Encoding…')
+  await flow.encode()
+
+  deps.onStatus('Registering blob (approve in wallet)…')
+  const regTx = flow.register({ owner: deps.address, epochs: deps.epochs, deletable: false })
+  regTx.setSenderIfNotSet(deps.address)
+  await regTx.build({ client: deps.suiClient })
+  const reg = await deps.executor.signAndExecute(regTx)
+  await deps.executor.waitForTransaction(reg.digest)
+
+  deps.onStatus('Uploading to the relay…')
+  await flow.upload({ digest: reg.digest })
+
+  deps.onStatus('Certifying (approve in wallet)…')
+  const certTx = flow.certify()
+  certTx.setSenderIfNotSet(deps.address)
+  await certTx.build({ client: deps.suiClient })
+  const cert = await deps.executor.signAndExecute(certTx)
+  await deps.executor.waitForTransaction(cert.digest)
+
+  const blob = await flow.getBlob()
+  return { blobId: blob.blobId, url: walrusBlobUrl(deps.network, blob.blobId), digest: cert.digest }
+}