@3mate/walrus-sponsor-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 3mate Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @3mate/walrus-sponsor-sdk
+
+Official SDK for [3mate Walrus Sponsor](https://github.com/3MateLabs/walrus-sponsor-sdk) — sponsored blob storage on the [Walrus](https://walrus.space) network.
+
+Zero runtime dependencies. Works in Node.js 18+ and modern browsers.
+
+## Install
+
+```bash
+npm install @3mate/walrus-sponsor-sdk
+```
+
+## Quick Start
+
+```typescript
+import { WalrusSponsor } from "@3mate/walrus-sponsor-sdk";
+
+const walrus = new WalrusSponsor({
+  apiKey: "sbk_live_...",
+  baseUrl: "https://your-backend.com",
+});
+
+// Upload a file (browser)
+const file = document.querySelector<HTMLInputElement>("#file")!.files![0];
+const result = await walrus.upload(file, {
+  creatorAddress: "0x123...",
+  epochs: 3,
+});
+
+console.log("View:", walrus.getBlobUrl(result.blobId));
+```
+
+## API
+
+### Constructor
+
+```typescript
+new WalrusSponsor({
+  apiKey: string;         // Required — your API key (sbk_live_...)
+  baseUrl: string;        // Required — your backend URL
+  aggregatorUrl?: string; // Optional — defaults to mainnet aggregator
+});
+```
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `health()` | Check if backend is live |
+| `epoch()` | Get current Walrus epoch info |
+| `estimateCost(size, epochs?)` | Estimate WAL storage cost |
+| `upload(file, opts)` | Upload a file via sponsored publisher |
+| `listBlobs(opts?)` | List blobs with optional filters |
+| `getBlob(id)` | Get single blob details |
+| `getBlobUrl(blobId)` | Build aggregator URL (no network call) |
+
+### Upload
+
+```typescript
+// Browser — File or Blob
+await walrus.upload(file, { creatorAddress: "0x..." });
+
+// Node.js — Buffer
+await walrus.upload(
+  { data: buffer, filename: "photo.png", contentType: "image/png" },
+  { creatorAddress: "0x...", epochs: 3 }
+);
+```
+
+Options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `creatorAddress` | `string` | — | Required. Sui address to own the blob |
+| `epochs` | `number` | `1` | Storage duration in epochs |
+| `deletable` | `boolean` | `true` | Whether the blob can be deleted |
+
+### List & Get Blobs
+
+```typescript
+const { blobs, total } = await walrus.listBlobs({
+  status: "active",
+  creatorAddress: "0x...",
+  limit: 10,
+  offset: 0,
+});
+
+const blob = await walrus.getBlob("0x1234...");
+```
+
+### Estimate Cost
+
+```typescript
+const cost = await walrus.estimateCost(1024 * 1024, 3); // 1 MB, 3 epochs
+console.log(cost.totalCost);   // WAL amount as string
+console.log(cost.storageCost); // storage component
+console.log(cost.writeCost);   // write component
+```
+
+### Error Handling
+
+```typescript
+import { WalrusSponsorError } from "@3mate/walrus-sponsor-sdk";
+
+try {
+  await walrus.upload(file, opts);
+} catch (err) {
+  if (err instanceof WalrusSponsorError) {
+    console.error(err.message);    // Human-readable message
+    console.error(err.statusCode); // 401, 402, 502, etc.
+    console.error(err.details);    // Raw API error body
+  }
+}
+```
+
+| Status | Meaning |
+|--------|---------|
+| 401 | Invalid or missing API key |
+| 402 | Insufficient workspace balance |
+| 502 | Storage service unavailable |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,199 @@
+interface WalrusSponsorConfig {
+    /** API key (starts with sbk_live_) */
+    apiKey: string;
+    /** Base URL of your walrus-sponsor backend */
+    baseUrl: string;
+    /** Walrus aggregator URL for blob retrieval (default: mainnet aggregator) */
+    aggregatorUrl?: string;
+}
+interface UploadOptions {
+    /** Sui address that will own the SponsoredBlob (0x-prefixed, 64 hex chars) */
+    creatorAddress: string;
+    /** Storage duration in epochs (default: 1) */
+    epochs?: number;
+    /** Whether the blob can be deleted (default: true) */
+    deletable?: boolean;
+}
+interface ListBlobsOptions {
+    /** Filter by status */
+    status?: "active" | "deleted" | "expired" | "transferred";
+    /** Filter by creator address */
+    creatorAddress?: string;
+    /** Max results (default: 50) */
+    limit?: number;
+    /** Pagination offset (default: 0) */
+    offset?: number;
+}
+interface HealthResponse {
+    status: string;
+    timestamp: string;
+}
+interface EpochResponse {
+    currentEpoch: number;
+    startTime: string;
+    endTime: string;
+    epochDurationDays: number;
+}
+interface StorageCostEstimate {
+    size: number;
+    epochs: number;
+    storageCost: string;
+    writeCost: string;
+    totalCost: string;
+    totalCostNumber: number;
+}
+interface SponsoredBlob {
+    sponsoredBlobId: string;
+    blobId: string;
+    creatorAddress: string;
+    sponsorAddress: string;
+    txDigest: string;
+    sizeBytes: number;
+    walCost: number;
+    gasFee: number;
+    totalCharged: number;
+    endEpoch: number;
+    status: string;
+}
+interface AlreadyCertifiedBlob {
+    blobId: string;
+    endEpoch: number;
+    alreadyCertified: true;
+    txDigest: string;
+}
+type UploadResult = SponsoredBlob | AlreadyCertifiedBlob;
+interface BlobSummary {
+    id: string;
+    objectId: string;
+    blobId: string;
+    creatorAddress: string;
+    sponsorAddress: string;
+    sizeBytes: number;
+    contentType: string | null;
+    filename: string | null;
+    endEpoch: number;
+    status: string;
+    createdAt: string;
+}
+interface BlobDetail extends BlobSummary {
+    txDigest: string;
+    sponsorCanDelete: boolean;
+    autoRenew: boolean;
+    autoRenewEpochs: number | null;
+    updatedAt: string;
+}
+interface ListBlobsResponse {
+    blobs: BlobSummary[];
+    total: number;
+}
+/** Browser File/Blob or Node.js Buffer with metadata */
+type FileInput = File | Blob | Buffer | {
+    data: Buffer;
+    filename: string;
+    contentType?: string;
+};
+declare class WalrusSponsorError extends Error {
+    statusCode: number;
+    details?: any;
+    constructor(message: string, statusCode: number, details?: any);
+}
+declare class WalrusSponsor {
+    private apiKey;
+    private baseUrl;
+    private aggregatorUrl;
+    constructor(config: WalrusSponsorConfig);
+    private request;
+    /**
+     * Check backend health (no auth required).
+     *
+     * @example
+     * ```ts
+     * const h = await walrus.health();
+     * console.log(h.status); // "ok"
+     * ```
+     */
+    health(): Promise<HealthResponse>;
+    /**
+     * Get current Walrus epoch info (no auth required).
+     *
+     * @example
+     * ```ts
+     * const e = await walrus.epoch();
+     * console.log(e.currentEpoch);
+     * ```
+     */
+    epoch(): Promise<EpochResponse>;
+    /**
+     * Estimate WAL storage cost for a given file size and epoch count.
+     *
+     * @param size - File size in bytes
+     * @param epochs - Storage duration in epochs (default: 1)
+     *
+     * @example
+     * ```ts
+     * const cost = await walrus.estimateCost(1024 * 1024, 3);
+     * console.log(cost.totalCost);
+     * ```
+     */
+    estimateCost(size: number, epochs?: number): Promise<StorageCostEstimate>;
+    /**
+     * Upload a file to Walrus via the sponsored publisher.
+     *
+     * @param file - File, Blob, Buffer, or { data, filename, contentType }
+     * @param opts - Upload options (creatorAddress required)
+     *
+     * @example
+     * ```ts
+     * // Browser
+     * const input = document.querySelector<HTMLInputElement>("#file");
+     * const result = await walrus.upload(input.files[0], {
+     *   creatorAddress: "0x123...",
+     *   epochs: 3,
+     * });
+     *
+     * // Node.js
+     * const buf = fs.readFileSync("photo.png");
+     * const result = await walrus.upload(
+     *   { data: buf, filename: "photo.png", contentType: "image/png" },
+     *   { creatorAddress: "0x123...", epochs: 3 }
+     * );
+     * ```
+     */
+    upload(file: FileInput, opts: UploadOptions): Promise<UploadResult>;
+    /**
+     * List sponsored blobs for the current API key.
+     *
+     * @example
+     * ```ts
+     * const { blobs, total } = await walrus.listBlobs({ status: "active", limit: 10 });
+     * ```
+     */
+    listBlobs(opts?: ListBlobsOptions): Promise<ListBlobsResponse>;
+    /**
+     * Get details of a single sponsored blob.
+     *
+     * @param id - Blob object_id or database id
+     *
+     * @example
+     * ```ts
+     * const blob = await walrus.getBlob("0x1234...");
+     * console.log(blob.status, blob.endEpoch);
+     * ```
+     */
+    getBlob(id: string): Promise<BlobDetail>;
+    /**
+     * Build the aggregator URL for retrieving a blob's content.
+     * This is a client-side helper — no network call.
+     *
+     * @param blobId - The Walrus blob ID (base64url encoded)
+     *
+     * @example
+     * ```ts
+     * const url = walrus.getBlobUrl("Aqz5l...");
+     * // => "https://aggregator.walrus-mainnet.walrus.space/v1/Aqz5l..."
+     * ```
+     */
+    getBlobUrl(blobId: string): string;
+}
+
+export { type AlreadyCertifiedBlob, type BlobDetail, type BlobSummary, type EpochResponse, type FileInput, type HealthResponse, type ListBlobsOptions, type ListBlobsResponse, type SponsoredBlob, type StorageCostEstimate, type UploadOptions, type UploadResult, WalrusSponsor, type WalrusSponsorConfig, WalrusSponsorError, WalrusSponsor as default };

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+interface WalrusSponsorConfig {
+    /** API key (starts with sbk_live_) */
+    apiKey: string;
+    /** Base URL of your walrus-sponsor backend */
+    baseUrl: string;
+    /** Walrus aggregator URL for blob retrieval (default: mainnet aggregator) */
+    aggregatorUrl?: string;
+}
+interface UploadOptions {
+    /** Sui address that will own the SponsoredBlob (0x-prefixed, 64 hex chars) */
+    creatorAddress: string;
+    /** Storage duration in epochs (default: 1) */
+    epochs?: number;
+    /** Whether the blob can be deleted (default: true) */
+    deletable?: boolean;
+}
+interface ListBlobsOptions {
+    /** Filter by status */
+    status?: "active" | "deleted" | "expired" | "transferred";
+    /** Filter by creator address */
+    creatorAddress?: string;
+    /** Max results (default: 50) */
+    limit?: number;
+    /** Pagination offset (default: 0) */
+    offset?: number;
+}
+interface HealthResponse {
+    status: string;
+    timestamp: string;
+}
+interface EpochResponse {
+    currentEpoch: number;
+    startTime: string;
+    endTime: string;
+    epochDurationDays: number;
+}
+interface StorageCostEstimate {
+    size: number;
+    epochs: number;
+    storageCost: string;
+    writeCost: string;
+    totalCost: string;
+    totalCostNumber: number;
+}
+interface SponsoredBlob {
+    sponsoredBlobId: string;
+    blobId: string;
+    creatorAddress: string;
+    sponsorAddress: string;
+    txDigest: string;
+    sizeBytes: number;
+    walCost: number;
+    gasFee: number;
+    totalCharged: number;
+    endEpoch: number;
+    status: string;
+}
+interface AlreadyCertifiedBlob {
+    blobId: string;
+    endEpoch: number;
+    alreadyCertified: true;
+    txDigest: string;
+}
+type UploadResult = SponsoredBlob | AlreadyCertifiedBlob;
+interface BlobSummary {
+    id: string;
+    objectId: string;
+    blobId: string;
+    creatorAddress: string;
+    sponsorAddress: string;
+    sizeBytes: number;
+    contentType: string | null;
+    filename: string | null;
+    endEpoch: number;
+    status: string;
+    createdAt: string;
+}
+interface BlobDetail extends BlobSummary {
+    txDigest: string;
+    sponsorCanDelete: boolean;
+    autoRenew: boolean;
+    autoRenewEpochs: number | null;
+    updatedAt: string;
+}
+interface ListBlobsResponse {
+    blobs: BlobSummary[];
+    total: number;
+}
+/** Browser File/Blob or Node.js Buffer with metadata */
+type FileInput = File | Blob | Buffer | {
+    data: Buffer;
+    filename: string;
+    contentType?: string;
+};
+declare class WalrusSponsorError extends Error {
+    statusCode: number;
+    details?: any;
+    constructor(message: string, statusCode: number, details?: any);
+}
+declare class WalrusSponsor {
+    private apiKey;
+    private baseUrl;
+    private aggregatorUrl;
+    constructor(config: WalrusSponsorConfig);
+    private request;
+    /**
+     * Check backend health (no auth required).
+     *
+     * @example
+     * ```ts
+     * const h = await walrus.health();
+     * console.log(h.status); // "ok"
+     * ```
+     */
+    health(): Promise<HealthResponse>;
+    /**
+     * Get current Walrus epoch info (no auth required).
+     *
+     * @example
+     * ```ts
+     * const e = await walrus.epoch();
+     * console.log(e.currentEpoch);
+     * ```
+     */
+    epoch(): Promise<EpochResponse>;
+    /**
+     * Estimate WAL storage cost for a given file size and epoch count.
+     *
+     * @param size - File size in bytes
+     * @param epochs - Storage duration in epochs (default: 1)
+     *
+     * @example
+     * ```ts
+     * const cost = await walrus.estimateCost(1024 * 1024, 3);
+     * console.log(cost.totalCost);
+     * ```
+     */
+    estimateCost(size: number, epochs?: number): Promise<StorageCostEstimate>;
+    /**
+     * Upload a file to Walrus via the sponsored publisher.
+     *
+     * @param file - File, Blob, Buffer, or { data, filename, contentType }
+     * @param opts - Upload options (creatorAddress required)
+     *
+     * @example
+     * ```ts
+     * // Browser
+     * const input = document.querySelector<HTMLInputElement>("#file");
+     * const result = await walrus.upload(input.files[0], {
+     *   creatorAddress: "0x123...",
+     *   epochs: 3,
+     * });
+     *
+     * // Node.js
+     * const buf = fs.readFileSync("photo.png");
+     * const result = await walrus.upload(
+     *   { data: buf, filename: "photo.png", contentType: "image/png" },
+     *   { creatorAddress: "0x123...", epochs: 3 }
+     * );
+     * ```
+     */
+    upload(file: FileInput, opts: UploadOptions): Promise<UploadResult>;
+    /**
+     * List sponsored blobs for the current API key.
+     *
+     * @example
+     * ```ts
+     * const { blobs, total } = await walrus.listBlobs({ status: "active", limit: 10 });
+     * ```
+     */
+    listBlobs(opts?: ListBlobsOptions): Promise<ListBlobsResponse>;
+    /**
+     * Get details of a single sponsored blob.
+     *
+     * @param id - Blob object_id or database id
+     *
+     * @example
+     * ```ts
+     * const blob = await walrus.getBlob("0x1234...");
+     * console.log(blob.status, blob.endEpoch);
+     * ```
+     */
+    getBlob(id: string): Promise<BlobDetail>;
+    /**
+     * Build the aggregator URL for retrieving a blob's content.
+     * This is a client-side helper — no network call.
+     *
+     * @param blobId - The Walrus blob ID (base64url encoded)
+     *
+     * @example
+     * ```ts
+     * const url = walrus.getBlobUrl("Aqz5l...");
+     * // => "https://aggregator.walrus-mainnet.walrus.space/v1/Aqz5l..."
+     * ```
+     */
+    getBlobUrl(blobId: string): string;
+}
+
+export { type AlreadyCertifiedBlob, type BlobDetail, type BlobSummary, type EpochResponse, type FileInput, type HealthResponse, type ListBlobsOptions, type ListBlobsResponse, type SponsoredBlob, type StorageCostEstimate, type UploadOptions, type UploadResult, WalrusSponsor, type WalrusSponsorConfig, WalrusSponsorError, WalrusSponsor as default };

package/dist/index.js

@@ -0,0 +1,264 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  WalrusSponsor: () => WalrusSponsor,
+  WalrusSponsorError: () => WalrusSponsorError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_AGGREGATOR_URL = "https://aggregator.walrus-mainnet.walrus.space";
+var ERROR_MAP = {
+  401: "Invalid or missing API key",
+  402: "Insufficient workspace balance",
+  404: "Resource not found",
+  502: "Storage service unavailable \u2014 publisher may be down"
+};
+var WalrusSponsorError = class extends Error {
+  constructor(message, statusCode, details) {
+    super(message);
+    this.name = "WalrusSponsorError";
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+};
+function toCamelCase(obj) {
+  const out = {};
+  for (const key of Object.keys(obj)) {
+    const camel = key.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    const val = obj[key];
+    out[camel] = val !== null && typeof val === "object" && !Array.isArray(val) ? toCamelCase(val) : val;
+  }
+  return out;
+}
+function buildFormData(file, opts) {
+  const fd = new FormData();
+  if (typeof File !== "undefined" && file instanceof File) {
+    fd.append("file", file);
+  } else if (typeof Blob !== "undefined" && file instanceof Blob) {
+    fd.append("file", file, "upload");
+  } else if (Buffer.isBuffer(file)) {
+    fd.append("file", new Blob([new Uint8Array(file)]), "upload");
+  } else if (typeof file === "object" && "data" in file && Buffer.isBuffer(file.data)) {
+    const blob = new Blob([new Uint8Array(file.data)], {
+      type: file.contentType || "application/octet-stream"
+    });
+    fd.append("file", blob, file.filename);
+  } else {
+    throw new WalrusSponsorError(
+      "Invalid file input \u2014 provide a File, Blob, Buffer, or { data, filename }",
+      400
+    );
+  }
+  fd.append("creator_address", opts.creatorAddress);
+  if (opts.epochs !== void 0) fd.append("epochs", String(opts.epochs));
+  if (opts.deletable !== void 0)
+    fd.append("deletable", String(opts.deletable));
+  return fd;
+}
+var WalrusSponsor = class {
+  constructor(config) {
+    if (!config.apiKey) throw new Error("apiKey is required");
+    if (!config.baseUrl) throw new Error("baseUrl is required");
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.aggregatorUrl = (config.aggregatorUrl || DEFAULT_AGGREGATOR_URL).replace(/\/+$/, "");
+  }
+  // ── Internal fetch wrapper ────────────────────────────────────────────
+  async request(method, path, opts) {
+    const auth = opts?.auth ?? true;
+    let url = `${this.baseUrl}${path}`;
+    if (opts?.query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v !== void 0) params.append(k, String(v));
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    const headers = {};
+    if (auth) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    let body;
+    if (opts?.formData) {
+      body = opts.formData;
+    } else if (opts?.body) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(opts.body);
+    }
+    let res;
+    try {
+      res = await fetch(url, { method, headers, body });
+    } catch (err) {
+      throw new WalrusSponsorError(
+        `Network error: ${err instanceof Error ? err.message : "Unknown error"}`,
+        0,
+        err
+      );
+    }
+    if (!res.ok) {
+      let message = ERROR_MAP[res.status] || `Request failed (${res.status})`;
+      let details;
+      try {
+        const data2 = await res.json();
+        if (data2.error) message = data2.error;
+        details = data2;
+      } catch {
+      }
+      throw new WalrusSponsorError(message, res.status, details);
+    }
+    const data = await res.json();
+    return data;
+  }
+  // ── Public methods ────────────────────────────────────────────────────
+  /**
+   * Check backend health (no auth required).
+   *
+   * @example
+   * ```ts
+   * const h = await walrus.health();
+   * console.log(h.status); // "ok"
+   * ```
+   */
+  async health() {
+    return this.request("GET", "/health", { auth: false });
+  }
+  /**
+   * Get current Walrus epoch info (no auth required).
+   *
+   * @example
+   * ```ts
+   * const e = await walrus.epoch();
+   * console.log(e.currentEpoch);
+   * ```
+   */
+  async epoch() {
+    const raw = await this.request("GET", "/epoch", { auth: false });
+    return toCamelCase(raw);
+  }
+  /**
+   * Estimate WAL storage cost for a given file size and epoch count.
+   *
+   * @param size - File size in bytes
+   * @param epochs - Storage duration in epochs (default: 1)
+   *
+   * @example
+   * ```ts
+   * const cost = await walrus.estimateCost(1024 * 1024, 3);
+   * console.log(cost.totalCost);
+   * ```
+   */
+  async estimateCost(size, epochs) {
+    const raw = await this.request("GET", "/v1/storage-cost", {
+      query: { size, epochs }
+    });
+    return toCamelCase(raw);
+  }
+  /**
+   * Upload a file to Walrus via the sponsored publisher.
+   *
+   * @param file - File, Blob, Buffer, or { data, filename, contentType }
+   * @param opts - Upload options (creatorAddress required)
+   *
+   * @example
+   * ```ts
+   * // Browser
+   * const input = document.querySelector<HTMLInputElement>("#file");
+   * const result = await walrus.upload(input.files[0], {
+   *   creatorAddress: "0x123...",
+   *   epochs: 3,
+   * });
+   *
+   * // Node.js
+   * const buf = fs.readFileSync("photo.png");
+   * const result = await walrus.upload(
+   *   { data: buf, filename: "photo.png", contentType: "image/png" },
+   *   { creatorAddress: "0x123...", epochs: 3 }
+   * );
+   * ```
+   */
+  async upload(file, opts) {
+    if (!opts.creatorAddress)
+      throw new WalrusSponsorError("creatorAddress is required", 400);
+    const fd = buildFormData(file, opts);
+    const raw = await this.request("POST", "/v1/upload", {
+      formData: fd
+    });
+    return toCamelCase(raw);
+  }
+  /**
+   * List sponsored blobs for the current API key.
+   *
+   * @example
+   * ```ts
+   * const { blobs, total } = await walrus.listBlobs({ status: "active", limit: 10 });
+   * ```
+   */
+  async listBlobs(opts) {
+    const raw = await this.request("GET", "/v1/blobs", {
+      query: {
+        status: opts?.status,
+        creator_address: opts?.creatorAddress,
+        limit: opts?.limit,
+        offset: opts?.offset
+      }
+    });
+    return {
+      blobs: (raw.blobs || []).map((b) => toCamelCase(b)),
+      total: raw.total
+    };
+  }
+  /**
+   * Get details of a single sponsored blob.
+   *
+   * @param id - Blob object_id or database id
+   *
+   * @example
+   * ```ts
+   * const blob = await walrus.getBlob("0x1234...");
+   * console.log(blob.status, blob.endEpoch);
+   * ```
+   */
+  async getBlob(id) {
+    const raw = await this.request("GET", `/v1/blobs/${id}`);
+    return toCamelCase(raw);
+  }
+  /**
+   * Build the aggregator URL for retrieving a blob's content.
+   * This is a client-side helper — no network call.
+   *
+   * @param blobId - The Walrus blob ID (base64url encoded)
+   *
+   * @example
+   * ```ts
+   * const url = walrus.getBlobUrl("Aqz5l...");
+   * // => "https://aggregator.walrus-mainnet.walrus.space/v1/Aqz5l..."
+   * ```
+   */
+  getBlobUrl(blobId) {
+    return `${this.aggregatorUrl}/v1/${blobId}`;
+  }
+};
+var index_default = WalrusSponsor;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WalrusSponsor,
+  WalrusSponsorError
+});

package/dist/index.mjs

@@ -0,0 +1,238 @@
+// src/index.ts
+var DEFAULT_AGGREGATOR_URL = "https://aggregator.walrus-mainnet.walrus.space";
+var ERROR_MAP = {
+  401: "Invalid or missing API key",
+  402: "Insufficient workspace balance",
+  404: "Resource not found",
+  502: "Storage service unavailable \u2014 publisher may be down"
+};
+var WalrusSponsorError = class extends Error {
+  constructor(message, statusCode, details) {
+    super(message);
+    this.name = "WalrusSponsorError";
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+};
+function toCamelCase(obj) {
+  const out = {};
+  for (const key of Object.keys(obj)) {
+    const camel = key.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    const val = obj[key];
+    out[camel] = val !== null && typeof val === "object" && !Array.isArray(val) ? toCamelCase(val) : val;
+  }
+  return out;
+}
+function buildFormData(file, opts) {
+  const fd = new FormData();
+  if (typeof File !== "undefined" && file instanceof File) {
+    fd.append("file", file);
+  } else if (typeof Blob !== "undefined" && file instanceof Blob) {
+    fd.append("file", file, "upload");
+  } else if (Buffer.isBuffer(file)) {
+    fd.append("file", new Blob([new Uint8Array(file)]), "upload");
+  } else if (typeof file === "object" && "data" in file && Buffer.isBuffer(file.data)) {
+    const blob = new Blob([new Uint8Array(file.data)], {
+      type: file.contentType || "application/octet-stream"
+    });
+    fd.append("file", blob, file.filename);
+  } else {
+    throw new WalrusSponsorError(
+      "Invalid file input \u2014 provide a File, Blob, Buffer, or { data, filename }",
+      400
+    );
+  }
+  fd.append("creator_address", opts.creatorAddress);
+  if (opts.epochs !== void 0) fd.append("epochs", String(opts.epochs));
+  if (opts.deletable !== void 0)
+    fd.append("deletable", String(opts.deletable));
+  return fd;
+}
+var WalrusSponsor = class {
+  constructor(config) {
+    if (!config.apiKey) throw new Error("apiKey is required");
+    if (!config.baseUrl) throw new Error("baseUrl is required");
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.aggregatorUrl = (config.aggregatorUrl || DEFAULT_AGGREGATOR_URL).replace(/\/+$/, "");
+  }
+  // ── Internal fetch wrapper ────────────────────────────────────────────
+  async request(method, path, opts) {
+    const auth = opts?.auth ?? true;
+    let url = `${this.baseUrl}${path}`;
+    if (opts?.query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v !== void 0) params.append(k, String(v));
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    const headers = {};
+    if (auth) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    let body;
+    if (opts?.formData) {
+      body = opts.formData;
+    } else if (opts?.body) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(opts.body);
+    }
+    let res;
+    try {
+      res = await fetch(url, { method, headers, body });
+    } catch (err) {
+      throw new WalrusSponsorError(
+        `Network error: ${err instanceof Error ? err.message : "Unknown error"}`,
+        0,
+        err
+      );
+    }
+    if (!res.ok) {
+      let message = ERROR_MAP[res.status] || `Request failed (${res.status})`;
+      let details;
+      try {
+        const data2 = await res.json();
+        if (data2.error) message = data2.error;
+        details = data2;
+      } catch {
+      }
+      throw new WalrusSponsorError(message, res.status, details);
+    }
+    const data = await res.json();
+    return data;
+  }
+  // ── Public methods ────────────────────────────────────────────────────
+  /**
+   * Check backend health (no auth required).
+   *
+   * @example
+   * ```ts
+   * const h = await walrus.health();
+   * console.log(h.status); // "ok"
+   * ```
+   */
+  async health() {
+    return this.request("GET", "/health", { auth: false });
+  }
+  /**
+   * Get current Walrus epoch info (no auth required).
+   *
+   * @example
+   * ```ts
+   * const e = await walrus.epoch();
+   * console.log(e.currentEpoch);
+   * ```
+   */
+  async epoch() {
+    const raw = await this.request("GET", "/epoch", { auth: false });
+    return toCamelCase(raw);
+  }
+  /**
+   * Estimate WAL storage cost for a given file size and epoch count.
+   *
+   * @param size - File size in bytes
+   * @param epochs - Storage duration in epochs (default: 1)
+   *
+   * @example
+   * ```ts
+   * const cost = await walrus.estimateCost(1024 * 1024, 3);
+   * console.log(cost.totalCost);
+   * ```
+   */
+  async estimateCost(size, epochs) {
+    const raw = await this.request("GET", "/v1/storage-cost", {
+      query: { size, epochs }
+    });
+    return toCamelCase(raw);
+  }
+  /**
+   * Upload a file to Walrus via the sponsored publisher.
+   *
+   * @param file - File, Blob, Buffer, or { data, filename, contentType }
+   * @param opts - Upload options (creatorAddress required)
+   *
+   * @example
+   * ```ts
+   * // Browser
+   * const input = document.querySelector<HTMLInputElement>("#file");
+   * const result = await walrus.upload(input.files[0], {
+   *   creatorAddress: "0x123...",
+   *   epochs: 3,
+   * });
+   *
+   * // Node.js
+   * const buf = fs.readFileSync("photo.png");
+   * const result = await walrus.upload(
+   *   { data: buf, filename: "photo.png", contentType: "image/png" },
+   *   { creatorAddress: "0x123...", epochs: 3 }
+   * );
+   * ```
+   */
+  async upload(file, opts) {
+    if (!opts.creatorAddress)
+      throw new WalrusSponsorError("creatorAddress is required", 400);
+    const fd = buildFormData(file, opts);
+    const raw = await this.request("POST", "/v1/upload", {
+      formData: fd
+    });
+    return toCamelCase(raw);
+  }
+  /**
+   * List sponsored blobs for the current API key.
+   *
+   * @example
+   * ```ts
+   * const { blobs, total } = await walrus.listBlobs({ status: "active", limit: 10 });
+   * ```
+   */
+  async listBlobs(opts) {
+    const raw = await this.request("GET", "/v1/blobs", {
+      query: {
+        status: opts?.status,
+        creator_address: opts?.creatorAddress,
+        limit: opts?.limit,
+        offset: opts?.offset
+      }
+    });
+    return {
+      blobs: (raw.blobs || []).map((b) => toCamelCase(b)),
+      total: raw.total
+    };
+  }
+  /**
+   * Get details of a single sponsored blob.
+   *
+   * @param id - Blob object_id or database id
+   *
+   * @example
+   * ```ts
+   * const blob = await walrus.getBlob("0x1234...");
+   * console.log(blob.status, blob.endEpoch);
+   * ```
+   */
+  async getBlob(id) {
+    const raw = await this.request("GET", `/v1/blobs/${id}`);
+    return toCamelCase(raw);
+  }
+  /**
+   * Build the aggregator URL for retrieving a blob's content.
+   * This is a client-side helper — no network call.
+   *
+   * @param blobId - The Walrus blob ID (base64url encoded)
+   *
+   * @example
+   * ```ts
+   * const url = walrus.getBlobUrl("Aqz5l...");
+   * // => "https://aggregator.walrus-mainnet.walrus.space/v1/Aqz5l..."
+   * ```
+   */
+  getBlobUrl(blobId) {
+    return `${this.aggregatorUrl}/v1/${blobId}`;
+  }
+};
+var index_default = WalrusSponsor;
+export {
+  WalrusSponsor,
+  WalrusSponsorError,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@3mate/walrus-sponsor-sdk",
+  "version": "0.1.0",
+  "description": "Official SDK for 3mate Walrus Sponsor — Sponsored blob storage on Walrus",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "walrus",
+    "sui",
+    "blob",
+    "storage",
+    "sponsor",
+    "web3",
+    "3mate"
+  ],
+  "author": "3mate Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/3MateLabs/walrus-sponsor-sdk"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  }
+}