@3mate/walrus-sponsor-sdk 0.1.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 3mate Labs
+Copyright (c) 2025 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

package/README.md

@@ -1,6 +1,9 @@
 # @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.
+[![npm version](https://img.shields.io/npm/v/@3mate/walrus-sponsor-sdk)](https://www.npmjs.com/package/@3mate/walrus-sponsor-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Official SDK & CLI for [Walrus Sponsor Service](https://walrus-sponsor.krill.tube) — sponsored blob storage on the [Walrus](https://walrus.space) network.
 
 Zero runtime dependencies. Works in Node.js 18+ and modern browsers.
 
@@ -8,117 +11,210 @@ Zero runtime dependencies. Works in Node.js 18+ and modern browsers.
 
 ```bash
 npm install @3mate/walrus-sponsor-sdk
+
+# For CLI usage (global)
+npm install -g @3mate/walrus-sponsor-sdk
 ```
 
 ## Quick Start
 
+### SDK (programmatic)
+
 ```typescript
 import { WalrusSponsor } from "@3mate/walrus-sponsor-sdk";
 
-const walrus = new WalrusSponsor({
+const client = new WalrusSponsor({
   apiKey: "sbk_live_...",
-  baseUrl: "https://your-backend.com",
+  // baseUrl defaults to https://walrus-sponsor.krill.tube
+});
+
+// Upload a file (Node.js)
+const result = await client.upload("./photo.jpg", {
+  creatorAddress: "0x123...",
+  epochs: 5,
 });
 
-// Upload a file (browser)
+console.log("Blob ID:", result.blob_id);
+console.log("View:", client.getBlobUrl(result.blob_id));
+
+// Upload a file (Browser)
 const file = document.querySelector<HTMLInputElement>("#file")!.files![0];
-const result = await walrus.upload(file, {
+const browserResult = await client.upload(file, {
   creatorAddress: "0x123...",
   epochs: 3,
 });
+```
+
+### CLI
+
+```bash
+# Configure (API key stored in OS keychain — never plaintext on disk)
+krilly config set-key sbk_live_abc123...
+
+# Upload
+krilly upload ./photo.jpg --creator 0x123... --epochs 5
 
-console.log("View:", walrus.getBlobUrl(result.blobId));
+# List blobs
+krilly blobs --status active --pretty
+
+# Get blob details
+krilly blob 0xabc...
+
+# Estimate cost
+krilly cost --size 1048576 --epochs 3 --pretty
 ```
 
-## API
+## API Reference
 
 ### 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
+  apiKey: string;              // Required — sbk_live_...
+  baseUrl?: string;            // Default: https://walrus-sponsor.krill.tube
+  aggregatorUrl?: string;      // Default: https://aggregator.walrus-mainnet.walrus.space
 });
 ```
 
 ### 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
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `health()` | Check if service is live | `{ status, timestamp }` |
+| `epoch()` | Get current Walrus epoch info | `{ currentEpoch, startTime, endTime }` |
+| `storageCost(size, epochs)` | Estimate WAL storage cost | `{ total_cost, storage_cost, write_cost }` |
+| `upload(file, opts)` | Upload file (sponsor pays WAL) | `{ blob_id, tx_digest, ... }` |
+| `blobs(opts?)` | List blobs (filter by status/creator) | `{ blobs[], total }` |
+| `blob(id)` | Get single blob detail | `BlobDetail` |
+| `delete(blobId, systemObjId)` | Delete blob, reclaim storage | `{ tx_digest, storage_returned }` |
+| `extend(opts)` | Extend blob storage duration | `{ new_end_epoch, tx_digest }` |
+| `fund(blobId, coinId)` | Add WAL funds to a blob | `{ tx_digest }` |
+| `register(opts)` | Advanced: client-side upload step 1 | `{ blob_object_id, tx_digest }` |
+| `certify(opts)` | Advanced: client-side upload step 2 | `{ sponsored_blob_id, tx_digest }` |
+| `getBlobUrl(blobId)` | Get aggregator download URL | `string` |
+
+### Upload Options
 
 ```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 }
-);
+client.upload(file, {
+  creatorAddress: "0x...",  // Required — who owns the blob
+  epochs: 5,               // Storage duration (default: 1)
+  deletable: true,         // Allow deletion before expiry (default: true)
+  filename: "photo.jpg",   // Optional filename override
+  contentType: "image/jpeg", // Optional MIME type
+});
 ```
 
-Options:
+The `file` parameter accepts:
+- **Node.js**: `string` (file path), `Buffer`, `Uint8Array`, `ReadableStream`
+- **Browser**: `File`, `Blob`
 
-| 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 |
+## CLI Commands
 
-### List & Get Blobs
+### Config
 
-```typescript
-const { blobs, total } = await walrus.listBlobs({
-  status: "active",
-  creatorAddress: "0x...",
-  limit: 10,
-  offset: 0,
-});
-
-const blob = await walrus.getBlob("0x1234...");
+```bash
+krilly config set-key <api_key>        # Save API key (OS keychain)
+krilly config set-url <url>            # Set backend URL
+krilly config set-aggregator <url>     # Set aggregator URL
+krilly config show                     # Show current config
 ```
 
-### Estimate Cost
+> 🔒 API keys are stored in your OS keychain (macOS Keychain / Linux libsecret).
+> Falls back to AES-256-GCM encrypted file if keychain is unavailable.
 
-```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
+### Operations
+
+```bash
+krilly health
+krilly epoch
+krilly cost --size <bytes> --epochs <n>
+
+krilly upload <file> --creator <address> [--epochs <n>] [--deletable]
+krilly blobs [--status <s>] [--creator <addr>] [--limit <n>] [--offset <n>]
+krilly blob <id>
+krilly delete <id> --system-object <id>
+krilly extend <id> --epochs <n> --system-object <id> --payment-coin <id>
+krilly fund <id> --coin <id>
+
+krilly url <blob_id>
 ```
 
-### Error Handling
+Add `--pretty` to any command for formatted JSON output.
+
+## Error Handling
 
 ```typescript
-import { WalrusSponsorError } from "@3mate/walrus-sponsor-sdk";
+import { WalrusSponsor, WalrusSponsorError } from "@3mate/walrus-sponsor-sdk";
+
+const client = new WalrusSponsor({ apiKey: "sbk_live_..." });
 
 try {
-  await walrus.upload(file, opts);
+  await client.upload("./file.txt", { creatorAddress: "0x..." });
 } 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
+    console.error(`API Error [${err.status}]: ${err.message}`);
+    // err.code — e.g. "INSUFFICIENT_BALANCE", "RATE_LIMIT_EXCEEDED"
   }
 }
 ```
 
-| Status | Meaning |
-|--------|---------|
-| 401 | Invalid or missing API key |
-| 402 | Insufficient workspace balance |
-| 502 | Storage service unavailable |
+## Security
+
+- API keys are **never stored in plaintext** on disk
+- macOS: stored in Keychain (`security` CLI)
+- Linux: stored in GNOME Keyring / KDE Wallet (`secret-tool`)
+- Fallback: AES-256-GCM encrypted file at `~/.krilly/.vault`
+- Non-secret config (`baseUrl`) stored in `~/.krilly/config.json`
 
 ## License
 
-MIT
+MIT — [3mate Labs](https://github.com/3MateLabs)
+
+## AI Agent Integration
+
+Krilly is designed to be agent-friendly. Give your AI agent decentralized storage in one line:
+
+```typescript
+import { WalrusSponsor } from "krilly";
+
+const walrus = new WalrusSponsor({
+  apiKey: process.env.WALRUS_API_KEY, // set in agent environment
+});
+
+// Upload agent-generated content
+const result = await walrus.upload(
+  { data: Buffer.from(output), filename: "report.json", contentType: "application/json" },
+  { creatorAddress: "0x...", epochs: 5 }
+);
+
+// Permanent, decentralized URL — no auth needed to read
+const url = walrus.getBlobUrl(result.blob_id);
+```
+
+### For Agent Frameworks
+
+Each SDK method maps 1:1 to a tool/function call:
+
+| Tool | Method | Description |
+|------|--------|-------------|
+| `walrus_upload` | `upload(file, opts)` | Store file on Walrus |
+| `walrus_list` | `blobs(opts?)` | List stored blobs |
+| `walrus_get` | `blob(id)` | Get blob metadata |
+| `walrus_cost` | `estimateCost(size, epochs)` | Estimate cost |
+| `walrus_delete` | `delete(id, sysObj)` | Delete blob |
+| `walrus_extend` | `extend(opts)` | Extend storage |
+| `walrus_url` | `getBlobUrl(id)` | Get download URL |
+
+Works with LangChain, CrewAI, AutoGPT, OpenClaw, or any framework that supports npm packages.
+
+### CLI for Shell-Based Agents
+
+```bash
+export WALRUS_API_KEY=sbk_live_...
+krilly config set-key $WALRUS_API_KEY
+krilly upload ./data.json --creator 0x... --epochs 5
+krilly blobs --pretty
+```
+
+See full docs: https://walrus-sponsor.krill.tube/docs/ai-agents