@meddleware/walrus-client 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meddleware/walrus-client",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "description": "Walrus decentralised storage client and asset management utilities for Sui applications.",
   "author": "MeddleWare <meddleware@proton.me>",
@@ -9,7 +9,12 @@
     "type": "git",
     "url": "git+https://github.com/meddleware-org/walrus-client.git"
   },
-  "keywords": ["walrus", "sui", "decentralised-storage", "web3"],
+  "keywords": [
+    "walrus",
+    "sui",
+    "decentralised-storage",
+    "web3"
+  ],
   "files": [
     "src",
     "CHANGELOG.md"
@@ -24,7 +29,8 @@
   },
   "dependencies": {
     "@mysten/sui": "~2.17.0",
-    "@mysten/walrus": "~1.1.7"
+    "@mysten/walrus": "~1.1.7",
+    "@meddleware/nft-gate-client": "~0.0.3"
   },
   "devDependencies": {
     "@types/node": "~24.12.2",
@@ -34,4 +40,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/access.ts

@@ -1,76 +1,70 @@
 /**
  * NFT-gated relay access helpers.
  *
- * When the MeddleWare upload relay runs behind an `nft-gate` auth gateway, an upload must
+ * When the Meddleware upload relay runs behind an `nft-gate` auth gateway, an upload must
  * carry a wallet-signed **access proof** proving the caller holds the required access NFT.
  * These helpers build that proof; the resulting token is passed to
  * `createWalrusClient({ uploadRelayAuthToken })`, which threads it as the relay
  * `Authorization: Bearer` header (see `client.ts`).
  *
- * The wire format mirrors `@meddleware/nft-gate-client` (challenge, signed message, and
- * base64-JSON proof token). It is duplicated here — rather than depended upon — so this
- * package stays self-contained; the gateway (`nft-gate-gateway`) is the authority that
- * verifies these proofs.
- *
- * TODO(unify): once `@meddleware/nft-gate-client` is published (from the `nft-gate`
- * standalone workspace, canonical vault location `blockchain/sui/packages/nft-gate-client-sui/`),
- * import `fetchChallenge`/`buildAccessProof`/`personalMessageForNonce` from it and delete the
- * duplicated logic below (keep this module as the thin Walrus-facing wrapper).
+ * Core primitives are imported from `@meddleware/nft-gate-client` (the canonical package).
+ * This module re-exports them under Walrus-friendly aliases and adds the one-shot
+ * `createRelayAccessToken` convenience function.
  */
 
+import {
+  type Challenge,
+  type AccessProof,
+  type PersonalMessageSigner,
+  personalMessageForNonce,
+  encodeAccessProof,
+  fetchChallenge,
+} from '@meddleware/nft-gate-client'
+
+// ── Re-exports under Walrus-client aliases ────────────────────────────────────
+
 /** A server-issued, time-bound challenge from the gateway's `GET /v1/challenge`. */
-export interface RelayChallenge {
-  nonce: string
-  expiresAt: number
-}
+export type RelayChallenge = Challenge
 
 /** The proof payload; `consumeDigest` is present only for single-use gates. */
-export interface AccessProofInput {
-  address: string
-  nonce: string
-  signature: string
-  consumeDigest?: string
-}
+export type AccessProofInput = AccessProof
 
 /** A wallet personal-message signer (e.g. wallet-standard `sui:signPersonalMessage`). */
-export type PersonalMessageSigner = (message: Uint8Array) => Promise<{ signature: string }>
+export type { PersonalMessageSigner }
 
 /** The exact bytes the wallet signs for a nonce. MUST match the gateway's derivation. */
-export function personalMessageForNonce(nonce: string): Uint8Array {
-  return new TextEncoder().encode(`nft-gate:access:${nonce}`)
-}
+export { personalMessageForNonce }
 
-function toBase64(s: string): string {
-  return typeof btoa === 'function' ? btoa(s) : Buffer.from(s, 'utf-8').toString('base64')
-}
-
-/** Encode a proof as the base64(JSON) Bearer token the relay auth header carries. */
+/**
+ * Encode a proof as the base64(JSON) Bearer token the relay auth header carries.
+ *
+ * @throws {Error} if `JSON.stringify` or `btoa` is unavailable in the environment.
+ */
 export function buildAccessProofToken(proof: AccessProofInput): string {
-  const payload: AccessProofInput = {
-    address: proof.address,
-    nonce: proof.nonce,
-    signature: proof.signature,
-  }
-  if (proof.consumeDigest) payload.consumeDigest = proof.consumeDigest
-  return toBase64(JSON.stringify(payload))
+  return encodeAccessProof(proof)
 }
 
-/** Fetch a fresh challenge from the gateway. Tolerates `expiresAt` or `expires_at`. */
-export async function fetchRelayChallenge(
+/**
+ * Fetch a fresh challenge from the gateway's `GET /v1/challenge` endpoint.
+ * Tolerates both `expiresAt` (camelCase) and `expires_at` (snake_case) response shapes.
+ *
+ * @throws {Error} if the network request fails or the gateway returns a non-2xx status.
+ * @throws {Error} if the response body is missing the required `nonce` field.
+ */
+export function fetchRelayChallenge(
   relayHost: string,
   opts: { signal?: AbortSignal } = {},
 ): Promise<RelayChallenge> {
-  const res = await fetch(`${relayHost.replace(/\/$/, '')}/v1/challenge`, { signal: opts.signal })
-  if (!res.ok) throw new Error(`challenge request failed: ${res.status}`)
-  const data = (await res.json()) as { nonce?: string; expiresAt?: number; expires_at?: number }
-  if (!data || typeof data.nonce !== 'string') throw new Error('challenge response missing nonce')
-  return { nonce: data.nonce, expiresAt: data.expiresAt ?? data.expires_at ?? 0 }
+  return fetchChallenge(relayHost, opts)
 }
 
 /**
- * One-shot: fetch a challenge, sign it with the wallet, and return the token to pass as
- * `createWalrusClient({ uploadRelayAuthToken })`. For single-use gates, supply the
- * `consumeDigest` of the on-chain consume transaction first.
+ * One-shot: fetch a challenge, sign it with the wallet, and return the encoded proof token
+ * to pass as `createWalrusClient({ uploadRelayAuthToken })`. For single-use gates, supply
+ * the `consumeDigest` of the on-chain consume transaction.
+ *
+ * @throws {Error} if the challenge fetch fails.
+ * @throws {Error} if the wallet signer rejects the message.
  */
 export async function createRelayAccessToken(opts: {
   relayHost: string
@@ -79,13 +73,13 @@ export async function createRelayAccessToken(opts: {
   consumeDigest?: string
   signal?: AbortSignal
 }): Promise<string> {
-  const challenge = await fetchRelayChallenge(opts.relayHost, { signal: opts.signal })
+  const challenge = await fetchChallenge(opts.relayHost, { signal: opts.signal })
   const message = personalMessageForNonce(challenge.nonce)
   const { signature } = await opts.sign(message)
-  return buildAccessProofToken({
+  return encodeAccessProof({
     address: opts.address,
     nonce: challenge.nonce,
     signature,
-    consumeDigest: opts.consumeDigest,
+    ...(opts.consumeDigest ? { consumeDigest: opts.consumeDigest } : {}),
   })
 }

package/src/client.ts

@@ -3,8 +3,10 @@ import { walrus, TESTNET_WALRUS_PACKAGE_CONFIG, MAINNET_WALRUS_PACKAGE_CONFIG }
 
 export { TESTNET_WALRUS_PACKAGE_CONFIG, MAINNET_WALRUS_PACKAGE_CONFIG }
 
+/** Supported Walrus network environments. */
 export type WalrusNetwork = 'testnet' | 'mainnet'
 
+/** Default Sui full-node RPC URLs, keyed by network. */
 export const DEFAULT_RPC_URLS: Record<WalrusNetwork, string> = {
   testnet: 'https://fullnode.testnet.sui.io:443',
   mainnet: 'https://fullnode.mainnet.sui.io:443',
@@ -40,27 +42,51 @@ export function walrusBlobUrl(
   return `${host}/v1/blobs/${blobId}`
 }
 
+/** Return the Walrus on-chain package config for the given network. */
 export function getWalrusPackageConfig(network: WalrusNetwork) {
   return network === 'mainnet' ? MAINNET_WALRUS_PACKAGE_CONFIG : TESTNET_WALRUS_PACKAGE_CONFIG
 }
 
+/** Options accepted by {@link createWalrusClient}. */
 export type CreateWalrusClientOptions = {
+  /** Target network (default `'testnet'`). */
   network?: WalrusNetwork
   /** Override the Sui JSON-RPC/gRPC fullnode URL. Defaults to the public Mysten endpoint for the network. */
   rpcUrl?: string
+  /** Optional WASM bundle URL for the Walrus WASM client. */
   wasmUrl?: string
+  /**
+   * Upload relay host URL. Defaults to the public Mysten relay for the network.
+   * Operators running their own relay (e.g. Meddleware's NFT-gated relay) should
+   * pass their relay URL here alongside `uploadRelayAuthToken`.
+   */
   uploadRelayHost?: string
+  /**
+   * Bearer token for the upload relay `Authorization` header. Obtain via
+   * `createRelayAccessToken` from the `access` module when the relay is NFT-gated.
+   */
   uploadRelayAuthToken?: string
+  /**
+   * Maximum tip payment to the upload relay in MIST (default 1,000,000 = 0.001 SUI).
+   * The relay may request less; this cap prevents the client from overpaying.
+   */
   uploadRelayMaxTipMist?: number
   /**
    * When true, build a client with NO upload relay (direct-to-storage-node).
-   * Overrides `uploadRelayHost` and the default MeddleWare relay fallback, so a
-   * deployer is never hard-blocked on relay infra. Uploads then talk directly to
-   * Walrus storage nodes.
+   * Overrides `uploadRelayHost` and the default relay fallback. Useful for
+   * server-side Node.js scripts where relay infra is unnecessary.
    */
   disableUploadRelay?: boolean
 }
 
+/**
+ * Create a Walrus client pre-configured for the given network and relay options.
+ *
+ * @example
+ * ```ts
+ * const client = createWalrusClient({ network: 'testnet' })
+ * ```
+ */
 export function createWalrusClient({
   network = 'testnet',
   rpcUrl,

package/src/upload.ts

@@ -3,6 +3,7 @@ import { WalrusFile } from '@mysten/walrus'
 import type { Signer } from '@mysten/sui/cryptography'
 import type { createWalrusClient } from './client.js'
 
+/** The return type of {@link createWalrusClient}. */
 export type WalrusClient = ReturnType<typeof createWalrusClient>
 
 /**
@@ -23,17 +24,30 @@ export const MAX_SINGLE_RESERVATION_EPOCHS = 53
  */
 export const LONG_TERM_EPOCHS = 200
 
+/** Options shared by all upload helpers. */
 export type UploadOptions = {
+  /** Storage epochs to reserve (default: {@link MAX_SINGLE_RESERVATION_EPOCHS}). */
   epochs?: number
+  /** Whether the blob can be deleted by its owner (default false). */
   deletable?: boolean
+  /** Arbitrary key-value metadata tags stored with the blob. */
   tags?: Record<string, string>
 }
 
+/** The object IDs returned after a successful upload. */
 export type UploadResult = {
+  /** Walrus content-addressed blob ID. */
   blobId: string
+  /** On-chain Walrus blob object ID. */
   blobObjectId: string
 }
 
+/**
+ * Upload raw bytes as a Walrus quilt (file bundle). Use this from Node.js with a keypair
+ * signer; use {@link createUploadFlow} in the browser for wallet-popup-safe signing.
+ *
+ * @throws {Error} if the Walrus write transaction fails or the signer rejects.
+ */
 export async function uploadBytes(
   client: WalrusClient,
   contents: Uint8Array,
@@ -53,7 +67,11 @@ export async function uploadBytes(
   return { blobId: result.blobId, blobObjectId: result.id }
 }
 
-// Node.js only — reads a local file before uploading
+/**
+ * Read a local file and upload it as a Walrus quilt. Node.js only.
+ *
+ * @throws {Error} if the file cannot be read or the upload fails.
+ */
 export async function uploadLocalFile(
   client: WalrusClient,
   filePath: string,
@@ -65,7 +83,10 @@ export async function uploadLocalFile(
   return uploadBytes(client, new Uint8Array(contents), identifier, signer, options)
 }
 
-// Browser — returns a multi-step flow for wallet-popup-safe signing
+/**
+ * Begin a multi-step quilt upload flow suitable for browser wallet signing.
+ * The caller drives the flow: encode → register (wallet signs) → upload → certify (wallet signs).
+ */
 export function createUploadFlow(
   client: WalrusClient,
   contents: Uint8Array,
@@ -83,7 +104,12 @@ export function createUploadFlow(
 // wallets/explorers), use a RAW blob: `GET /v1/blobs/<blobId>` returns the exact
 // bytes. See `walrusBlobUrl()` in ./client.
 
-// Node.js — one-shot raw-blob upload with a keypair `Signer`.
+/**
+ * Upload raw bytes as a Walrus raw blob (served directly at `/v1/blobs/<blobId>`).
+ * Use this for assets that must be URL-addressable (e.g. token icons). Node.js only.
+ *
+ * @throws {Error} if the Walrus write transaction fails or the signer rejects.
+ */
 export async function uploadImageBytes(
   client: WalrusClient,
   contents: Uint8Array,
@@ -100,12 +126,18 @@ export async function uploadImageBytes(
   return { blobId: res.blobId, blobObjectId: res.blobObject.id }
 }
 
-// Browser — multi-step raw-blob flow for wallet-popup-safe signing. Drive it as:
-//   await flow.encode()
-//   const regTx = flow.register({ owner, epochs, deletable }) // wallet signs+executes
-//   await flow.upload({ digest })                              // digest of regTx
-//   const certTx = flow.certify()                              // wallet signs+executes
-//   const { blobId } = await flow.getBlob()                    // -> walrusBlobUrl(...)
+/**
+ * Begin a multi-step raw-blob upload flow suitable for browser wallet signing.
+ *
+ * Drive the returned flow:
+ * ```ts
+ * await flow.encode()
+ * const regTx = flow.register({ owner, epochs, deletable }) // wallet signs + executes
+ * await flow.upload({ digest })                              // digest of regTx
+ * const certTx = flow.certify()                              // wallet signs + executes
+ * const { blobId } = await flow.getBlob()                   // use walrusBlobUrl(network, blobId)
+ * ```
+ */
 export function createBlobUploadFlow(client: WalrusClient, contents: Uint8Array) {
   return client.walrus.writeBlobFlow({ blob: contents })
 }